# Model Context Protocol (MCP) Learn how to use the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) to enable AI agents to securely access and interact with your Intercom data whenever helpful. Region availability The Intercom MCP server is available for US and EU hosted workspaces. AU hosted workspaces are not yet supported. Connect using the endpoint that matches your workspace's hosted region — see the connection URLs below. ## What is Model Context Protocol? MCP is a protocol that enables AI tools and applications to connect with Intercom's data and services in a secure, standardized way. It provides a structured method for AI models to: - Find and retrieve Intercom data (conversations, contacts, etc.) - Access specific tools and functionality provided by Intercom - Maintain context about your Intercom workspace when working with AI assistants ## How MCP Works Intercom hosts a remote MCP server that follows the authenticated remote MCP specification ([docs](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization)). This server handles requests from AI tools and provides access to Intercom data through a secure interface. **Connection URLs:** Use the endpoint for your workspace's hosted region. You can tell your region from your workspace URL: `app.intercom.com` is US hosted and `app.eu.intercom.com` is EU hosted. | Region | Streamable HTTP (Recommended) | Legacy SSE (deprecated) | | --- | --- | --- | | US | `https://mcp.intercom.com/mcp` | `https://mcp.intercom.com/sse` | | EU | `https://mcp.eu.intercom.com/mcp` | `https://mcp.eu.intercom.com/sse` | Requests to the EU endpoint are processed within the EU, in line with Intercom's [Regional Data Hosting](https://www.intercom.com/help/en/articles/6124430-regional-data-hosting) commitments. When an AI tool or application needs to access Intercom data: 1. The tool connects to Intercom's MCP server 2. Authentication verifies the user's permissions 3. The tool can then access relevant Intercom data and functionality 4. The connection remains live to receive updates as needed ## Benefits of Using MCP - **Secure Access**: All data access is authenticated and authorized - **Standardized Interface**: Consistent interaction pattern across different AI tools - **Contextual Understanding**: AI assistants maintain awareness of your Intercom environment - **Increased Development Efficiency**: Retrieve and interpret customer data from Intercom via your internal AI tools to be more efficient in your work ## Available Tools The Intercom MCP Server provides **14 tools** for interacting with the Intercom API. Workspaces with Fin Operator also get the [Fin Operator tools](#fin-operator-tools). ### Universal Tools #### **search** Universal search tool for finding conversations and contacts using a query DSL approach. **Key Features:** - **Must specify** `object_type:conversations` or `object_type:contacts` to indicate which API to call - Supports complex field-based queries with operators (eq, neq, gt, lt, contains, etc.) - Returns summary results with IDs prefixed by type (`conversation_*` or `contact_*`) - Built-in pagination support with `starting_after` parameter - Free-text search capability with `q:` parameter **Example Queries:** ``` object_type:conversations state:open source_type:email object_type:contacts email_domain:"example.com" object_type:conversations source_body:contains:"refund" limit:20 object_type:conversations team_assignee_id:15 object_type:conversations admin_assignee_id:6 ``` **Pagination:** - Results are paginated with up to 150 items per page (default 5, set with `limit:` parameter) - When more results exist, the response includes a `_note` with the cursor to use - To fetch the next page, add `starting_after:cursor_value` to your query - Example: `object_type:conversations state:open starting_after:cursor_abc123` **Response includes:** - `total_in_page`: Count of results in current page - `results`: Array of result objects with IDs prefixed by type - `pages`: Pagination metadata (when available) - `_note`: Helpful hint when more pages exist (e.g., "More results available. To get the next page, add to your query: starting_after:cursor_abc123") #### **fetch** Retrieve complete detailed information for specific resources. **Key Features:** - Use IDs returned from search results (prefixed with `conversation_`, `contact_`, or `company_`) - Returns full resource details including metadata, conversation parts, custom attributes - Includes direct links to Intercom app for easy navigation ### Direct API Tools #### **search_conversations** Search conversations by specific IDs with advanced filtering options including source type, author details, state, assignment fields (team_assignee_id, admin_assignee_id), and timing statistics. **Key Filter Parameters:** - `ids`: Array of conversation IDs - `source_type`: Filter by source type (email, chat, etc.) - `source_author_name`, `source_author_email`: Filter by author details - `state`: Filter by conversation state (open, closed, snoozed) - `team_assignee_id`: Filter by team assignee ID (string) - `admin_assignee_id`: Filter by admin assignee ID (number) - `statistics_time_to_assignment`, `statistics_time_to_admin_reply`, `statistics_time_to_first_close`: Filter by timing statistics with operators (<, >, =, !=, <=, >=) **Pagination Support:** - Results are paginated with up to 150 items per page (default 5) - If more results exist, the response includes a `pages` object with `pages.next.starting_after` cursor - To fetch the next page, make another request with the SAME search parameters plus the `starting_after` value from the previous response - Continue until `pages.next` is not present in the response **Response includes:** - `total_in_page`: Count of results in current page - `conversations`: Array of conversation objects - `pages`: Pagination metadata (when available) - `_note`: Helpful hint when more pages exist #### **get_conversation** Retrieve a single conversation by ID with complete details including all conversation parts and metadata. #### **search_contacts** Search contacts by IDs, name, email, phone, custom attributes, or email domain with flexible matching options. **Pagination Support:** - Results are paginated with up to 150 items per page (default 5) - If more results exist, the response includes a `pages` object with `pages.next.starting_after` cursor - To fetch the next page, make another request with the SAME search parameters plus the `starting_after` value from the previous response - Continue until `pages.next` is not present in the response **Response includes:** - `total_in_page`: Count of results in current page - `data`: Array of contact objects - `pages`: Pagination metadata (when available) - `_note`: Helpful hint when more pages exist #### **get_contact** Get complete contact information including custom attributes, location data, and activity timestamps. #### **list_companies** List companies with optional filters. **Key Filter Parameters:** - `name`: Find a company by exact name match (returns single company) - `company_id`: Find a company by external company_id (returns single company) - `tag_id`: Filter companies by tag ID - `segment_id`: Filter companies by segment ID - `per_page`: Results per page (default 15, max 60) - `page`: Page number (default 1) Uses page-based pagination. Response includes `total_count` and `pages` with `total_pages`. #### **get_company** Retrieve complete details for a specific company including all custom attributes, segments, and tags. #### **list_articles** List all articles in the Intercom Help Center. **Key Parameters:** - `page`: Page number to retrieve (default 1) - `per_page`: Articles per page (1-150, default 25) Uses page-based pagination. Response includes `pages` with `total_pages`. #### **search_articles** Search for articles in the Intercom Help Center. At least one search parameter must be provided. **Key Parameters:** - `phrase`: Free-text search across article title and body - `state`: Filter by `published` or `draft` - `help_center_id`: Filter by Help Center ID (numeric) - `highlight`: When true, returns highlighted matching snippets #### **get_article** Retrieve complete details for a specific article including full HTML body, metadata, and parent collection information. #### **create_article** Create a new article in the Intercom Help Center. **Required Parameters:** - `title`: The article title - `author_id`: Numeric ID of the admin/teammate who authored the article **Optional Parameters:** - `description`: A short summary - `body`: Article content in HTML format - `state`: `published` or `draft` (defaults to draft) - `parent_id`: Numeric ID of the parent collection or section - `parent_type`: `collection` or `section` (required if `parent_id` is set) #### **update_article** Update an existing article. At least one field to update must be provided. **Required Parameters:** - `id`: The article ID to update **Optional Parameters:** - `title`, `author_id`, `description`, `body`, `state`, `parent_id`, `parent_type` #### **add_internal_note** Add an internal note to a conversation. Notes are visible to teammates only — nothing is sent to the customer, and this tool cannot send customer-visible replies. Adding a note never changes the assignee, but a note on a conversation that is snoozed and assigned to someone other than the authorizing admin will unsnooze (reopen) it. **Required Parameters:** - `conversation_id`: A raw numeric ID (e.g., `12345`), the prefixed `conversation_12345` form, or an Intercom Inbox URL. Normalized automatically, and must resolve to a numeric conversation ID. Regular conversations only — ticket IDs are not supported and return an authorization error - `body`: The note content in HTML format (plain text is also accepted). Whitespace between block-level tags becomes empty paragraphs and renders as blank space, so emit tags without newlines or indentation between them The note is attributed to the admin who authorized the MCP connection — authorship cannot be set per call. **Response includes:** - The conversation ID and the created note part (`id`, `part_type`, `created_at`, `author`) — not the full conversation. A `part_type` of `note_and_unsnooze` means the note reopened the conversation. Use `get_conversation` to read the updated thread Requires the **Write conversations** permission in addition to read access. A 401 usually means the workspace's Intercom connection predates this permission — disconnect and reconnect the Intercom integration to grant it. ### Fin Operator tools Operator is Fin's internal AI agent. If your workspace has Fin Operator, the Intercom MCP server also lets your AI client ask Operator to do work inside your workspace, read the answers back, and review and apply the changes Operator proposes. The Fin Operator tools appear in the tool list only when all of the following are true. Otherwise they are not listed and cannot be called. - Your workspace has Fin Operator. - You connected with OAuth. Bearer token connections do not get the Fin Operator tools. - You can use Operator in Intercom. The tools are authorized as you, so you need the same permission over MCP that you need in the Intercom app. Connected before the Fin Operator tools were added? A connection made before the **Use Fin Operator** permission existed lists the tools but cannot call them: the first call returns an error asking you to reconnect. Some clients re-authorize automatically; in others, disconnect and reconnect the Intercom MCP server. Reconnecting also keeps every existing tool working. There are five Fin Operator tools: - `send_operator_message`: send Operator a message; collect the answer later - `get_operator_response`: read the latest response from an Operator chat - `get_proposal_details`: show what each pending proposal would change. Read-only - `apply_proposals`: apply proposals to your workspace's live configuration - `reject_proposals`: discard proposals Only `send_operator_message` uses Operator credits, in the same way as a turn started in Intercom; the other four tools are free. For parameters, response statuses, tool annotations, a typical workflow, rate limits and troubleshooting, see the [Fin Operator tools guide](/docs/guides/fin-operator-mcp). ## Setting things up ### Authentication Methods The MCP server supports **two authentication approaches**: 1. **OAuth Flow (Recommended)**: Browser-based authentication with a consent step, described below 2. **Bearer Token**: Direct API token authentication #### What to expect during OAuth When you connect a client with OAuth, your browser shows two screens in order: 1. **The Intercom MCP consent page.** This names the application asking to connect, lists what it will be able to do in your workspace, and shows its Client ID and the address it redirects to after you approve. Choose **Allow** to continue or **Cancel** to stop. Cancel grants nothing. 2. **Intercom's authorization screen.** This asks you to authorize access for Intercom MCP, the server, rather than for the application. After you authorize, you are returned to the application. Intercom's authorization screen can only name the Intercom MCP server, so the consent page is where you see and confirm which application receives access. The application name is supplied by the application itself and is not verified by Intercom. Check the redirect address Before you choose **Allow**, check that the **Redirects to** address belongs to the application you expect. If you did not start the connection yourself, or you do not recognize the application or the redirect address, choose **Cancel**. ### Configuration Examples Configuration Guide The examples below are generic templates. **Always refer to your specific LLM provider's official documentation** for the most up-to-date configuration instructions, as setup details may vary between versions and providers. These examples use the US endpoint. If your workspace is EU hosted, replace `https://mcp.intercom.com/mcp` with `https://mcp.eu.intercom.com/mcp`. See the connection URLs in [How MCP Works](#how-mcp-works). For **OAuth authentication** (recommended): ```json { "mcpServers": { "intercom": { "command": "npx", "args": [ "mcp-remote", "https://mcp.intercom.com/mcp" ] } } } ``` For **Bearer token authentication**: ```json { "mcpServers": { "intercom": { "command": "npx", "args": [ "mcp-remote", "https://mcp.intercom.com/mcp", "--header", "Authorization:${AUTH_HEADER}" ], "env": { "AUTH_HEADER": "Bearer YOUR_INTERCOM_API_TOKEN" } } } } ``` ### LLM Provider Setup Guides Each AI provider has specific setup instructions for MCP servers. Please consult the official documentation for your provider: - **Claude Desktop**: [MCP setup documentation](https://modelcontextprotocol.io/quickstart/user) - **Claude Code**: [MCP setup documentation](https://docs.anthropic.com/en/docs/claude-code/mcp) - **OpenAI**: [MCP integration guide](https://platform.openai.com/docs/guides/tools-remote-mcp) - **Claude.ai**: The Intercom connector in Claude's directory connects to US hosted workspaces. For an EU hosted workspace, go to Customize > Connectors > + Add > Add custom connector and use `https://mcp.eu.intercom.com/mcp`. On Claude Team or Enterprise, an org Owner adds it under Organization settings > Connectors. - **Cursor**: [MCP configuration guide](https://docs.cursor.com/context/model-context-protocol) - **Windsurf**: [MCP setup instructions](https://docs.windsurf.com/windsurf/cascade/mcp) - **VS Code**: [MCP integration docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) ### Connecting your own MCP client The providers listed above are already on the allowlist. If you're building your own MCP client, OAuth client registration is automatic — the server supports [Dynamic Client Registration](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization) — but every redirect URI a client registers is checked against an allowlist, which controls where the server will send authorization responses. What this means for your client: - **Bearer token authentication** doesn't use a redirect URI, so there's nothing to request. - **OAuth with a callback on `localhost` or `127.0.0.1`** is already allowed on any port, so you can develop and test locally right away. - **OAuth with any other callback** needs an allowlist entry before the flow will complete. Until we've added your redirect URI, registration and authorization fail with one of these errors: ``` Redirect URI https://your-app.example.com/callback is not in the allowlist, reach out to Intercom Customer Support if you believe we should support it ``` ``` Invalid request: Redirect URI is not allowed ``` App Store review is a separate approval Submitting your app for review in the Developer Hub doesn't add its redirect URI to the MCP server allowlist, even though you register the URI there. If your app connects to the MCP server with OAuth, request an allowlist entry as well. #### Requesting an allowlist entry Contact Intercom Customer Support through the Messenger in the bottom right of this page, and include: - The name of your client and what it does with Intercom data - Each redirect URI in full, exactly as your client sends it - The environment each URI serves: development, staging, or production - Your workspace ID - Whether you need a wildcard entry like `https://*.example.com`, and what it needs to cover We add the narrowest entry that covers your callbacks. For a host you own, that's usually the origin — an entry for `https://app.example.com` covers every path on that host. If your callback runs on a platform shared with other companies, we add the exact path instead, so list every path you use. Wildcards are granted only for domains where you control every subdomain. One entry covers both `mcp.intercom.com` and `mcp.eu.intercom.com`, so a single request is enough for both regions. ## Working with Pagination All search and list tools support pagination to handle large result sets efficiently. **Cursor-based pagination** is used by `search`, `search_conversations`, and `search_contacts` — use the `starting_after` parameter. **Page-based pagination** is used by `list_articles`, `list_companies` — use the `page` parameter. ### Example Pagination Workflow **1. Initial Search Request** Using the `search` tool: ``` object_type:conversations state:open limit:50 ``` **2. Response with More Results** If more results exist, you'll receive: ```json { "total_in_page": 50, "results": [...], "pages": { "type": "pages", "page": 1, "per_page": 50, "total_pages": 5, "next": { "page": 2, "starting_after": "cursor_abc123" } }, "_note": "More results available. To get the next page, add to your query: starting_after:cursor_abc123" } ``` **3. Fetch Next Page** Use the cursor from the response: ``` object_type:conversations state:open limit:50 starting_after:cursor_abc123 ``` **4. Continue Until Complete** Keep paginating until the response no longer includes `pages.next` or `_note`, indicating you've reached the last page. ### Tool-Specific Pagination For **`search_conversations`** and **`search_contacts`**, use the `starting_after` parameter: ```json { "state": "open", "per_page": 50, "starting_after": "cursor_abc123" } ``` The response will include the same pagination metadata to guide you through the result set. ## Required Scopes The Intercom MCP server requires the following permissions to access your workspace data. When using Bearer token authentication, ensure your access token includes these scopes. [Learn more about OAuth permissions](https://developers.intercom.com/docs/build-an-integration/learn-more/authentication/setting-up-oauth#permissions). - **Read and list users and companies**: Required for contact and company data access - **Read conversations**: Required for conversation data access - **Write conversations**: Required for adding internal notes to conversations (add_internal_note) - **Read and write articles**: Required for Help Center article access (list, search, get, create, update) - **Use Fin Operator**: Required for the [Fin Operator tools](#fin-operator-tools). Granted through OAuth only; it cannot be added to a Bearer token. During OAuth, the consent page summarizes these permissions as: view conversations and add internal notes to them, view contacts and companies, view, create and update articles, and use Fin Operator. The **Use Fin Operator** permission is requested for every connection, but the tools only appear for workspaces that have Fin Operator. ## MCP Inspector for Server Exploration Test the connection using: ```bash npx @modelcontextprotocol/inspector ``` Then connect to: - **Transport Type**: Streamable HTTP - **URL**: `https://mcp.intercom.com/mcp` (US) or `https://mcp.eu.intercom.com/mcp` (EU), or `/sse` for legacy ## Debugging and Troubleshooting MCP-Remote 1. **Authentication Problems** ```bash # Kill existing connections pkill -f mcp-remote # Clear MCP auth cache rm -rf ~/.mcp-auth ``` 2. **Connection Testing** ```bash # EU hosted workspaces: use https://mcp.eu.intercom.com/mcp instead # Test direct connection npx mcp-remote https://mcp.intercom.com/mcp # With bearer token npx mcp-remote https://mcp.intercom.com/mcp --header "Authorization:Bearer YOUR_TOKEN" ``` 3. **View Active MCP Connections** ```bash ps aux | grep mcp-remote | grep -v grep ``` ### Error Handling - **Invalid queries**: The search tool validates field names and operators, returning specific error messages - **Authentication failures**: Check token validity or restart OAuth flow - **Rate limiting**: Intercom API limits apply - reduce request frequency if needed ### Troubleshooting Tips - Restart AI Agent after configuration changes - Use the MCP Inspector to verify tool availability - Check browser console for OAuth-related errors - Verify Intercom API token permissions for bearer auth - The consent page expires after 15 minutes. If **Allow** shows "Authorization could not be completed", start the connection again from your client - Only one connection can be pending per browser. Starting a second connection in another tab before finishing the first makes the first tab's **Allow** fail with the same message. Start the connection again - An "Invalid redirect URI" error that says the URI does not match any registered URI for this client, shown before the consent page, means the client opened its callback on a port it did not register. Clear the client's saved authentication for the Intercom server (see Authentication Problems above) and connect again, so the client registers its current callback address - The consent page only appears in the OAuth flow. Bearer token authentication is unchanged - If you choose **Allow** and Intercom then shows "We're having technical difficulties", you most likely connected using another region's endpoint, for example the US endpoint for an EU hosted workspace. Remove the connection from your client and connect again using the endpoint for your workspace's region (see [How MCP Works](#how-mcp-works)). The MCP server isn't available for AU hosted workspaces.