> ## Documentation Index
> Fetch the complete documentation index at: https://docs.illumichat.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Integrations

> Connect your AI assistant to external tools like Notion and GitHub using the Model Context Protocol (MCP) for richer, more capable conversations.

## Overview

The **Model Context Protocol (MCP)** is a standard that lets AI assistants interact with external services and tools. With MCP integrations enabled, your IllumiChat assistant can search Notion pages, read GitHub repositories, create documents, list issues, and more -- all within a natural conversation.

<Note>
  MCP connections are configured at the workspace level. Once a provider is connected, all assistants in that workspace can use its tools during conversations.
</Note>

## What MCP Enables

| Without MCP                       | With MCP                                    |
| --------------------------------- | ------------------------------------------- |
| Answers from training data only   | Searches your Notion workspace in real time |
| Static knowledge base content     | Reads current GitHub repository files       |
| Cannot create external content    | Creates Notion pages from conversation      |
| No visibility into project issues | Lists and summarizes GitHub issues          |

## Available Integrations

<CardGroup cols={2}>
  <Card title="Notion" icon="file-lines">
    Search pages, read content, and create new pages in your Notion workspace.
  </Card>

  <Card title="GitHub" icon="github">
    Search repositories, read files, list issues, and search code across your organization.
  </Card>
</CardGroup>

## Setting Up Notion

<Steps>
  <Step title="Start the Connection">
    In your IllumiChat workspace, go to **Settings** > **Integrations** > **MCP**. Click **Connect** next to Notion.
  </Step>

  <Step title="Authorize with Notion">
    You will be redirected to Notion's OAuth authorization page. Sign in and select the pages and databases you want IllumiChat to access.

    <Tip>
      Start by granting access to a specific set of pages rather than your entire workspace. You can always expand access later.
    </Tip>
  </Step>

  <Step title="Confirm the Connection">
    After authorization, you will be redirected back to IllumiChat. The Notion integration will show as **Connected**.
  </Step>

  <Step title="Test in a Conversation">
    Open a chat with any assistant and try:

    * "Search my Notion for the Q4 planning document"
    * "What does the onboarding guide in Notion say?"
    * "Create a new Notion page titled 'Meeting Notes' with a summary of our discussion"
  </Step>
</Steps>

### Notion Tools

| Tool                  | What It Does                                | Example Query                                           |
| --------------------- | ------------------------------------------- | ------------------------------------------------------- |
| **Search Pages**      | Finds Notion pages matching a query         | "Find the product roadmap in Notion"                    |
| **Read Page Content** | Retrieves the full text of a page           | "Read the API documentation page"                       |
| **Create Page**       | Creates a new page under an existing parent | "Create a Notion page summarizing today's action items" |

### Tips

* **Page titles matter.** Search matches against page titles, so descriptive titles improve results.
* **Structure helps.** Well-organized Notion workspaces produce better search results.
* **Content extraction** converts Notion blocks to plain text. Complex layouts are simplified.

## Setting Up GitHub

<Steps>
  <Step title="Start the Connection">
    In workspace settings, go to **Integrations** > **MCP** and click **Connect** next to GitHub.
  </Step>

  <Step title="Install the GitHub App">
    You will be redirected to GitHub to install the IllumiChat GitHub App. Choose whether to install for all repositories or selected repositories.

    <Warning>
      For security, grant access only to the repositories your team needs. The assistant can read file contents from any repository it has access to.
    </Warning>
  </Step>

  <Step title="Authorize Access">
    After installing the GitHub App, authorize IllumiChat to access the app on your behalf.
  </Step>

  <Step title="Confirm and Test">
    Verify the connection shows as **Connected**. Test with:

    * "Search for repositories related to authentication"
    * "Show me the README from the main-app repo"
    * "List open issues in the frontend repository"
  </Step>
</Steps>

### GitHub Tools

| Tool                    | What It Does                        | Example Query                                  |
| ----------------------- | ----------------------------------- | ---------------------------------------------- |
| **Search Repositories** | Finds repositories matching a query | "Find repos related to microservices"          |
| **Read File Content**   | Retrieves a specific file           | "Show me the package.json from the API repo"   |
| **List Issues**         | Lists open, closed, or all issues   | "What are the open bugs in the frontend repo?" |
| **Search Code**         | Searches for code patterns          | "Find files that import the auth middleware"   |

### Tips

* **Be specific** when asking about files. Include the repository name and file path when you know them.
* **Issue queries** default to open issues. Ask for "closed issues" or "all issues" explicitly if needed.
* **Code search** works best with specific function names or unique strings rather than generic terms.

## Using MCP Tools in Chat

Once connected, MCP tools are available automatically. The AI decides when to use them based on conversation context. You do not need to explicitly request a specific tool.

### Examples

<Accordion title="Notion examples">
  * "What does our style guide say about button colors?" -- searches and reads from Notion
  * "Summarize the project brief for Project Atlas" -- finds and summarizes a Notion page
  * "Create a meeting notes page with these action items: ..." -- creates a new Notion page
</Accordion>

<Accordion title="GitHub examples">
  * "What dependencies does the backend use?" -- reads package.json from the repo
  * "Are there any open issues about login bugs?" -- searches issues
  * "Show me how the authentication middleware works" -- reads the source file
</Accordion>

### Multi-Tool Conversations

The assistant can use multiple MCP tools in a single response. For example:

> **You:** "Compare what our Notion docs say about the API rate limits with what's actually implemented in the codebase."
>
> The assistant will:
>
> 1. Search Notion for rate limit documentation
> 2. Read the relevant Notion page
> 3. Search GitHub for rate limit implementation
> 4. Read the source file
> 5. Provide a comparison

## Managing Connections

### Disconnecting a Provider

1. Go to **Settings** > **Integrations** > **MCP**
2. Click **Disconnect** next to the provider
3. Confirm the disconnection

<Note>
  Disconnecting immediately revokes access. Past conversation content retrieved via MCP is preserved in chat history.
</Note>

### Refreshing Connections

If a connection stops working (expired token, changed permissions), disconnect and reconnect the provider to generate a fresh access token.

## Security

* **OAuth tokens** are encrypted at rest using AES-256
* **Workspace scoping** -- connections are available only within the workspace where they were created
* **Admin only** -- only workspace owners and admins can manage MCP connections
* **Audit trail** -- all MCP tool invocations are logged in conversation history

## Troubleshooting

<Accordion title="Assistant not using MCP tools">
  * Verify the integration is connected in workspace settings
  * Try a direct request like "Search Notion for \[topic]" to force tool use
  * Ensure the assistant's model supports tool calling
</Accordion>

<Accordion title="Notion returns no results">
  * Confirm you granted access to the correct pages during OAuth setup
  * Try broader search terms; search matches page titles primarily
  * Reconnect if permissions were changed in Notion
</Accordion>

<Accordion title="GitHub file access denied">
  * Check that the GitHub App has access to the repository
  * For organization repos, ensure the App was installed at the org level
  * Reconnect if repository access permissions were changed
</Accordion>

## Next Steps

<CardGroup cols={2}>
  <Card title="Knowledge Base" icon="book" href="/features/knowledge-base">
    Combine MCP tools with a knowledge base for comprehensive answers
  </Card>

  <Card title="Web Search" icon="globe" href="/guides/web-search">
    Add real-time web search alongside MCP integrations
  </Card>
</CardGroup>