Overview
The Intercom integration lets users connect their Intercom workspace so Alysio can list and retrieve contacts, companies, segments, teams, events, and conversations on their behalf. Users can ask Alysio to list contacts or companies, get a contact or company by ID, list contacts attached to a company, list segments and teams, list events for a user, list or search conversations, and get conversation details—all in natural language. The integration uses OAuth 2.0; the user authorizes Intercom once and the MCP sends requests using the stored credential. Use intercom_list_all_contacts to get contact IDs (e.g. for events); use intercom_list_companies to get company IDs (e.g. for attached contacts).
Supported capabilities / objects
- Contacts — List all contacts (with pagination); get contact by ID.
- Companies — List companies (with pagination and order); get company by ID; list contacts attached to a company.
- Segments — List segments (optional include_count for contact counts).
- Teams — List all teams (with pagination).
- Events — List events for a user (pass contact’s external_id as user_id; get external_id from list_all_contacts).
- Conversations — List conversations (with pagination); get conversation by ID (returns up to 500 most recent in list); search conversations.
Authentication
Method: OAuth 2.0 (Intercom). The MCP sends requests using a Bearer token and a credential ID that identifies the user’s connected Intercom account. Requests are sent to the Intercom REST API.
Redirect URI: Configured when the Intercom integration is set up in Alysio. The Intercom OAuth app must allow this redirect URI in the Intercom Developer Hub.
Token handling
- OAuth tokens for the connected Intercom account are stored securely and refreshed automatically.
- Each user/tenant has their own credential; the MCP sends the appropriate credential ID with each request so calls are isolated per connection.
- On disconnect, that credential is no longer used and Intercom tools will not be available for that user until they reconnect Intercom.
Scope justification
| Scope / capability | Purpose |
|---|
| Contacts | List contacts, get contact by ID. |
| Companies | List companies, get company by ID, list contacts attached to a company. |
| Segments | List segments. |
| Teams | List teams. |
| Events | List events (per user/contact). |
| Conversations | List conversations, get conversation by ID, search conversations. |
Connection required: Users must connect Intercom in Alysio before Intercom tools work. If the connection is missing or expired, they may need to re-authorize in Settings → Integrations.
IDs for events and attached contacts: For intercom_list_events, pass the contact’s external_id as user_id; get external_id from intercom_list_all_contacts. For intercom_list_attach_contacts_to_company, get company_id from intercom_list_companies.
The Intercom MCP exposes the following tools. Users can invoke these capabilities through natural language in Alysio.
| Tool | Description | Example user prompts |
|---|
intercom_list_all_contacts | Lists all contacts in the Intercom workspace with optional pagination (page, per_page). | ”List Intercom contacts”, “Show first 50 contacts.” |
intercom_get_contact_by_id | Retrieves detailed information for a specific contact by ID. | ”Get contact 123”, “Show contact details.” |
intercom_list_companies | Lists all companies with optional pagination and order (asc/desc). | ”List our Intercom companies”, “Companies descending.” |
intercom_get_company_by_id | Retrieves detailed information for a specific company by ID. | ”Get company 456”, “Company details.” |
intercom_list_attach_contacts_to_company | Lists all contacts attached to a company; pass company_id (use intercom_list_companies for IDs). | ”Contacts at this company”, “Who’s attached to company X?” |
intercom_list_segments | Lists all segments with optional pagination and include_count for contact counts. | ”List segments”, “Segments with counts.” |
intercom_list_all_teams | Lists all teams in the Intercom workspace with optional pagination. | ”List Intercom teams”, “Show teams.” |
intercom_list_events | Lists events for a user; pass contact’s external_id as user_id (get from intercom_list_all_contacts). | ”Events for this contact”, “List user events.” |
intercom_list_conversations | Lists conversations with optional pagination. | ”List recent conversations”, “Show conversations.” |
intercom_get_conversation_by_id | Retrieves detailed information for a conversation by ID; list returns up to 500 most recent. | ”Get conversation 789”, “Conversation details.” |
intercom_search_conversations | Searches conversations with a query and optional pagination. | ”Search conversations about billing”, “Find conversations.” |
App Behavior
- API calls are made on-demand only when the user asks something that requires Intercom data (e.g. contacts, companies, segments, teams, events, conversations). There is no background sync; each request triggers the relevant Intercom API call using the user’s OAuth credential.
Example flow
- User asks: “List contacts at Acme Corp and show their recent events.”
- Alysio routes the request to the Intercom MCP.
- The MCP may call
intercom_list_companies to find Acme Corp’s company ID, then intercom_list_attach_contacts_to_company with that company_id, then for each contact (or a subset) call intercom_list_events with the contact’s external_id as user_id.
- The request is sent to the Intercom API using the user’s stored OAuth credential.
- The MCP returns the contact and event data; Alysio presents the results in chat.
Troubleshooting
Common issues
- Missing or expired connection — User sees errors or no Intercom data. Fix: Reconnect Intercom in Settings → Integrations (re-authorize via OAuth 2.0).
- 401 Unauthorized — Token invalid or expired. Fix: Re-authorize the integration in Settings → Integrations.
- 403 Forbidden — Insufficient OAuth scopes. Fix: Ensure the Intercom OAuth app has the required scopes for contacts, companies, segments, teams, events, and conversations (as used by the tools).
- Events need user_id — intercom_list_events requires user_id (the contact’s external_id). Fix: Call
intercom_list_all_contacts and use the contact’s external_id as user_id in list_events.
- Company ID for attached contacts — intercom_list_attach_contacts_to_company requires company_id. Fix: Call
intercom_list_companies to get company IDs, then pass the desired company_id.
- Conversation list limit — get_conversation_by_id notes that the conversation list returns at most 500 most recent. Fix: Use intercom_search_conversations to find older conversations; use list_conversations with pagination for recent ones.
Support
