MCP Gateway · Catalog
Intercom MCP server
OfficialIntercom MCP is the official Model Context Protocol server for Intercom, with OAuth and tools that let agents search conversations and contacts, look up companies, and read, create, and update articles. Connect it through the Speakeasy MCP Gateway and agents such as Claude, Cursor, and ChatGPT get one governed URL for it, with SSO, RBAC, and a full audit trail.
Behind the MCP Gateway
Run Intercom MCP behind the MCP Gateway
One URL for every agent, sign-in through your IdP, RBAC down to the tool, and every Intercom call inspected and logged.
Tools · 13
Each tool below can be allowed or denied per team and role at the MCP Gateway, and every call is inspected and logged.
search_conversations
Search for Intercom conversations using multiple filter criteria. Supports filtering by: - IDs: Search for specific conversation IDs - Source: Filter by source type (email, chat, etc.), author name/email - State: Filter by conversation state (open, closed, snoozed) - Assignment: Filter by team assignee ID or admin assignee ID - Statistics: Filter by response times and assignment metrics - AI Agent: Filter by Fin AI agent participation and resolution state Pagination: - 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 Returns a list of matching conversations with basic details. Use get_conversation for full details.
get_conversation
Retrieve complete details for a specific Intercom conversation. Returns: - Full conversation metadata (state, priority, timestamps) - Complete message history with all conversation parts - Associated contacts and tags - Assignment and team information Accepted ID formats: - Raw conversation ID (e.g., 123456789) - Prefixed ID (e.g., conversation_123456789) - Intercom URL (e.g., https://app.intercom.com/a/inbox/_/inbox/conversation/123456789) Tip: If you copied the ID from a search or fetch result, remove the 'conversation_' prefix. This tool also accepts the prefixed form and URLs and will normalize automatically. Use this after search_conversations to get full conversation content.
search_contacts
Search for Intercom contacts using multiple filter criteria. Supports filtering by: - IDs: Search for specific contact IDs - Email/Domain: Filter by email address or domain - Name/Phone: Search by contact name or phone number - Custom Attributes: Filter by any custom data fields Pagination: - 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 Returns a list of matching contacts with their attributes. Use get_contact for additional details.
get_contact
Retrieve complete details for a specific Intercom contact. Returns: - Full contact profile (name, email, phone, location) - Role and signup information - Custom attributes and metadata - Last seen and activity timestamps Accepted ID formats: - Raw contact ID (UUID) - Prefixed ID (e.g., contact_aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee) - Intercom URL (e.g., https://app.intercom.com/a/apps/_/users/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee) Tip: If you copied the ID from a search or fetch result, remove the 'contact_' prefix. This tool also accepts the prefixed form and URLs and will normalize automatically. Use this after search_contacts to get full contact information.
list_companies
List Intercom companies with optional filters. Supports: - name: Find a company by exact name match (returns a single company) - company_id: Find a company by its external company_id (returns a single company) - tag_id: Filter companies by tag ID - segment_id: Filter companies by segment ID Pagination: - Uses page-based pagination (not cursor-based) - Default: page 1, 15 companies per page (max 60) - Set 'per_page' (1-60) and 'page' to navigate results - Response includes total_count and pages with total_pages Note: name and company_id are exact-match lookups that return a single company. For browsing all companies, omit name and company_id and paginate through results. Use get_company for full details including all custom_attributes.
get_company
Retrieve complete details for a specific Intercom company. Returns: - Full company profile (name, company_id, plan, industry, size) - Monthly spend and user count - All custom_attributes with their values (critical for attribute auditing) - Associated segments and tags - Activity timestamps (remote_created_at, last_request_at) Accepted ID formats: - Raw company ID - Prefixed ID (e.g., company_abc123def456) - Intercom URL (e.g., https://app.intercom.com/a/apps/_/companies/abc123def456) Tip: If you copied the ID from a search or fetch result, remove the 'company_' prefix. This tool also accepts the prefixed form and URLs and will normalize automatically. Use this after list_companies to get full company information including all custom attributes.
search
Purpose: 1. Search for resources in Intercom (conversations and contacts) using a unified query approach. For companies, use the list_companies tool. 2. Note that only a subset of properties will be returned in search results. 3. For complete details, use the Fetch tool with the returned IDs. Usage: 1. MUST specify object_type:conversations OR object_type:contacts to indicate which API to call. 2. Use specific field searches for precise filtering (e.g., email:john@example.com). 3. Use the starting_after parameter for pagination when more results exist. 4. Combine multiple search criteria with logical operators for complex queries. Search Tool Response: 1. Returns results with id, title, text, and url for each match. 2. IDs are prefixed with 'conversation_' or 'contact_' to indicate type. 3. Use these IDs with the Fetch tool to get complete resource details. Note: When filtering by id/contact_ids in queries, provide raw IDs without prefixes. If you pass prefixed IDs to get_conversation/get_contact, they are accepted and normalized. Intercom Search Query DSL specification: • Tokens separated by spaces • Each token: key[:op]:value • op (optional; default "eq") ∈ { eq, neq, gt, gte, lt, lte, in, nin, contains } • value: unquoted (alphanumeric, no spaces) or quoted in single/double quotes (to include spaces) Common Parameters: – object_type (mandatory) → "conversations" or "contacts" (specifies which API to call) – q/query → free-text search across key fields – created_at/updated_at → timestamp filters (YYYY-MM-DD or Unix timestamp) – limit → max results (default 10, max 150) – starting_after → pagination cursor CONVERSATION SEARCH (object_type:conversations): Supported fields: – id → raw conversation ID (no 'conversation_' prefix) – state → conversation state ("open", "closed", "snoozed") – priority → conversation priority ("priority", "not_priority") – open → boolean indicating if conversation is open (true/false) – read → boolean indicating if conversation has been read (true/false) – waiting_since → timestamp indicating how long conversation has been waiting (Unix timestamp) – snoozed_until → timestamp until which conversation is snoozed (Unix timestamp) – created_at → timestamp when conversation was created (Unix timestamp or YYYY-MM-DD) – updated_at → timestamp of last update (Unix timestamp or YYYY-MM-DD) Source fields: – source_type → conversation source type ("conversation", "email", "facebook", "twitter", etc.) – source_id → identifier for the source – source_delivered_as → delivery method of the source – source_subject → subject line of the conversation – source_body → body content of the conversation – source_url → URL associated with the source – source_author_id → identifier of the author – source_author_type → type of author (e.g., "user", "admin") – source_author_name → name of the message author – source_author_email → email of the message author Assignment fields: – contact_ids → raw contact IDs (UUIDs) associated with the conversation (no 'contact_' prefix) – teammate_ids → identifiers of teammates involved – team_assignee_id → team ID assigned to the conversation – admin_assignee_id → admin ID assigned to the conversation – tag_ids → identifiers of tags associated with the conversation Channel: – channel_initiated → channel through which conversation was initiated Statistics fields: – statistics_time_to_assignment → time to assignment in seconds – statistics_time_to_admin_reply → time to admin reply in seconds – statistics_time_to_first_close → time to first close in seconds – statistics_time_to_last_close → time to last close in seconds – statistics_median_time_to_reply → median time to reply in seconds – statistics_first_contact_reply_at → timestamp of first contact reply – statistics_first_assignment_at → timestamp of first assignment – statistics_first_admin_reply_at → timestamp of first admin reply – statistics_first_close_at → timestamp of first close – statistics_last_assignment_at → timestamp of last assignment – statistics_last_assignment_admin_reply_at → timestamp of last assignment admin reply – statistics_last_contact_reply_at → timestamp of last contact reply – statistics_last_admin_reply_at → timestamp of last admin reply – statistics_last_close_at → timestamp of last close – statistics_last_closed_by_id → identifier of last person who closed the conversation – statistics_count_reopens → number of times conversation was reopened – statistics_count_assignments → number of times conversation was assigned – statistics_count_conversation_parts → number of parts in the conversation Rating fields: – conversation_rating_requested_at → timestamp when rating was requested – conversation_rating_replied_at → timestamp when rating was replied to – conversation_rating_score → score given in the rating – conversation_rating_remark → remarks given in the rating – conversation_rating_contact_id → identifier of contact who provided the rating – conversation_rating_admin_id → identifier of admin associated with the rating AI Agent fields: – ai_agent_participated → boolean indicating if Fin AI agent participated (true/false) – ai_agent_resolution_state → AI agent resolution state – ai_agent_last_answer_type → AI agent last answer type – ai_agent_rating → AI agent rating score – ai_agent_rating_remark → AI agent rating remark – ai_agent_source_type → AI agent source type – ai_agent_source_title → AI agent source title CONTACT SEARCH (object_type:contacts): Supported fields: – id → raw contact ID (UUID, no 'contact_' prefix) – name → contact name – email → contact email address – email_domain → email domain – phone → contact phone number – role → contact role ("user", "lead") – custom_attributes.* → any custom attribute field (e.g., custom_attributes.company) EXAMPLES: user: show me recent conversations query: object_type:conversations created_at:gt:1735689600 user: find open conversations from email query: object_type:conversations state:open source_type:email user: search for conversations from support emails query: object_type:conversations source_author_email:contains:"@support" user: find conversations with slow response times query: object_type:conversations statistics_time_to_admin_reply:gt:3600 user: find conversations about billing query: object_type:conversations source_subject:contains:"billing" user: find conversations mentioning refund query: object_type:conversations source_body:contains:"refund" user: find contacts named John query: object_type:contacts name:"John" user: find contacts from example.com domain query: object_type:contacts email_domain:"example.com" user: find contacts with specific custom attribute query: object_type:contacts custom_attributes.plan_status:"active" user: recent contact activity query: object_type:contacts updated_at:gt:1735689600 limit:50 user: find conversations for a specific contact query: object_type:conversations contact_ids:in:d2e3bde8-4fe4-4a74-9232-5f7458e7a4cb user: find conversations assigned to a specific team query: object_type:conversations team_assignee_id:12345 user: find conversations assigned to a specific admin query: object_type:conversations admin_assignee_id:67890 user: find conversations where Fin participated query: object_type:conversations ai_agent_participated:true Unsupported features: • Complex boolean logic beyond simple AND/OR • Fuzzy matching or proximity searches • Aggregations or analytics queries • Direct conversation content search (use source fields instead) • Real-time or streaming results
fetch
Retrieve detailed content for a specific Intercom resource by ID or URL. Use this tool when you have: - A prefixed ID from search results (e.g., 'conversation_123456', 'contact_abc-def-123', or 'company_abc123') - An Intercom URL (e.g., 'https://app.intercom.com/a/inbox/_/inbox/conversation/123456') Returns: - Full resource content with formatted text summary - Metadata including state, timestamps, and associations - Direct URL to view the resource in Intercom For raw IDs without prefixes, use the specific tools: - 'get_conversation' for conversation IDs - 'get_contact' for contact UUIDs - 'get_company' for company IDs
list_articles
List all articles in the Intercom Help Center. Returns a paginated list of articles with basic metadata. Pagination: - Uses page-based pagination (not cursor-based) - Default: page 1, 25 articles per page - Set 'per_page' (1–150) and 'page' to navigate results - Response includes 'pages' object with total_pages and page count Returns article summaries including id, title, state, and timestamps. Use get_article for full content.
search_articles
Search for articles in the Intercom Help Center. Supports filtering by: - phrase: Free-text search across article title and body - state: Filter by 'published' or 'draft' - help_centre_id: Filter articles by a specific Help Center (numeric ID, uses British spelling to match API) - highlight: When true, returns highlighted matching snippets At least one search parameter must be provided. Returns matching articles with relevance-ranked results. Use get_article for full content.
get_article
Retrieve complete details for a specific Intercom Help Center article. Returns: - Full article content including HTML body - Metadata: title, description, author, state - Timestamps: created_at, updated_at - Parent collection/section information - URL to view the article Use this after list_articles or search_articles to get full article content.
create_article
Create a new article in the Intercom Help Center. Required fields: - title: The article title - author_id: Numeric ID of the admin/teammate who authored the article Optional fields: - description: A short summary of the article - body: The article content in HTML format - state: 'published' or 'draft' (defaults to draft if not specified) - parent_id: Numeric ID of the parent collection or section - parent_type: 'collection' or 'section' (required if parent_id is set) Returns the created article with its new ID and all fields.
update_article
Update an existing article in the Intercom Help Center. Required: - id: The article ID to update Optional fields (only provided fields will be updated): - title: Update the article title - author_id: Change the author (numeric admin/teammate ID) - description: Update the short summary - body: Update the article content (HTML format) - state: Change to 'published' or 'draft' - parent_id: Move to a different collection or section (numeric ID) - parent_type: 'collection' or 'section' (required if parent_id is set) Returns the updated article with all fields.
Questions