Title: Model Context Protocol (MCP) | Intercom and Fin Developer Platform
URL Source: https://developers.intercom.com/docs/guides/mcp
Markdown Content:
Learn how to use the Model Context Protocol (MCP) 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). 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 commitments.
When an AI tool or application needs to access Intercom data:
- The tool connects to Intercom's MCP server
- Authentication verifies the user's permissions
- The tool can then access relevant Intercom data and functionality
- 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.
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 pageresults: Array of result objects with IDs prefixed by typepages: 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 IDssource_type: Filter by source type (email, chat, etc.)source_author_name, source_author_email: Filter by author detailsstate: 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 pageconversations: Array of conversation objectspages: 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 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 pagedata: Array of contact objectspages: Pagination metadata (when available)_note: Helpful hint when more pages exist
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 IDsegment_id: Filter companies by segment IDper_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 bodystate: Filter by published or drafthelp_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 titleauthor_id: Numeric ID of the admin/teammate who authored the article
Optional Parameters:
description: A short summarybody: Article content in HTML formatstate: published or draft (defaults to draft)parent_id: Numeric ID of the parent collection or sectionparent_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 errorbody: 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 laterget_operator_response: read the latest response from an Operator chatget_proposal_details: show what each pending proposal would change. Read-onlyapply_proposals: apply proposals to your workspace's live configurationreject_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.
Setting things up
Authentication Methods
The MCP server supports two authentication approaches:
- OAuth Flow (Recommended): Browser-based authentication with a consent step, described below
- 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:
- 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.
- 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.
For OAuth authentication (recommended):
{ "mcpServers": { "intercom": { "command": "npx", "args": [ "mcp-remote", "https://mcp.intercom.com/mcp" ] } }}
For Bearer token authentication:
{ "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:
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 — 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.
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.
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:
{ "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.
For search_conversations and search_contacts, use the starting_after parameter:
{ "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.
- 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. 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:
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
- Authentication Problems
Kill existing connections pkill -f mcp-remote# Clear MCP auth cache rm -rf ~/.mcp-auth
- Connection Testing
- View Active MCP Connections
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). The MCP server isn't available for AU hosted workspaces.