Skip to content

Add the Intercom connector #842

Open
Open

Description

@amaudruz

What

A Intercom connector, so that someone who connects their Intercom account in Switch Console can let their agents read and reply to Intercom conversations and look up contacts, as them.

Why

Support agents (human and AI) work in Intercom.

How

Intercom has an official remote MCP server at https://mcp.intercom.com/mcp (EU: mcp.eu.intercom.com) with OAuth and documented dynamic registration (docs). Redirects other than localhost need Intercom support, so check that Switch Console's loopback sign-in works.

Add a new entry, core/switch_core/connections/catalog/intercom/.

Follow Adding a connector in the service connections v2 design doc. A connector is usually a catalog entry plus a skill, with no code, in one of three shapes:

  1. a remote MCP server with OAuth (example: catalog/atlassian/)
  2. a command-line tool with OAuth (example: catalog/google-workspace/)
  3. a key the person pastes in (adapter: api_key, with mcp or cli; example: catalog/datadog/)

Prefer OAuth with dynamic registration where the vendor offers it, then a static OAuth app, then a key, and say in the PR why you chose that shape. If the vendor fits none of them, comment on this issue before writing broker code.

Locally, turn connections on with FEATURE_FLAGS_ENABLED=service_connections.

Rules every connector follows:

  • The token or key never reaches the coding tool (env, args or files); the session host makes the calls
  • Ask for the least access that works: no admin, org-wide or delete scopes without a written reason. Offer a read-only level if the vendor supports one
  • OAuth stays strict: HTTPS, PKCE S256, no new redirect hosts; don't loosen the loader's checks
  • CLIs run without a shell, from the vendor's official release pinned by SHA-256, with auth/config/admin commands denied
  • No real data in the repo: no tokens, tenant URLs or account ids in fixtures or screenshots
  • The logo is the official mark (viewBox and paths only), credited in NOTICE.md

Done when

  • connections/catalog/intercom/connection.yaml is complete and enabled: true, with comments on anything the vendor needs turned on and anything measured rather than documented (e.g. token lifetime)
  • skill/SKILL.md describes the tasks, tools and limits, with safe defaults (read before writing, confirm before deleting or closing), and never mentions credentials
  • It shows up in Switch Console's Connections with its name and logo, and connecting works (read-only and read-write, if both are offered)
  • Granted to an agent, its tools work in a session from a room; turning the grant off stops the session's access within a minute
  • An expiring token is renewed without the user doing anything (OAuth)
  • Disconnecting removes access (and revokes at the vendor where possible; for keys, the UI says Switch can't revoke them)
  • The token or key appears nowhere in the transcript, the room or the logs
  • Loader tests for the entry (core/tests/switch_core/connections/test_loader.py)
  • A short video of connect → grant → agent uses it in a room → grant off

Out of scope

Webhooks from the vendor into rooms; tool classification by level; connecting from the web dashboard.

Activity

  1. ANAMASGARD commented on Oct 21, 2026

    @ANAMASGARD

    Hi @amaudruz @petr-sandbox 👋 I'd love to work on this issue. Could you please assign it to me?

    My implementation approach

    1. Verify OAuth compatibility: Test Intercom's official remote MCP server with Switch Console's loopback login, OAuth discovery, dynamic registration, and PKCE S256. Check US/EU endpoints and redirect restrictions first.
    2. Add the connector: Create core/switch_core/connections/catalog/intercom/connection.yaml with enabled: true, using the existing Atlassian OAuth + MCP connector as a reference. Configure identity, supported access levels, and token handling.
    3. Add the skill: Create skill/SKILL.md covering conversation and contact lookups, safe tool usage, read-before-write behavior, and confirmation before sensitive actions.
    4. Add branding and tests: Include the official Intercom SVG, update the logo NOTICE.md, and extend core/tests/switch_core/connections/test_loader.py.
    5. End-to-end verification: Test Console connection → agent grant → MCP tool call from a room → grant removal within one minute → disconnect. Also verify token renewal and that credentials never appear in agent context, transcripts, or logs. I'll include a short demo video.

    Proposed architecture

    flowchart TD
        A["User opens Switch Console"] --> B["Connect Intercom"]
        B --> C["Core: OAuth discovery + PKCE S256"]
        C --> D{"Registration and redirect supported?"}
    
        D -->|Yes| E["Intercom consent"]
        D -->|No| F["Check approved static OAuth option"]
        F -->|Supported| E
        F -->|Blocked| X["Discuss blocker with maintainer"]
    
        E --> G["Core verifies identity and securely stores tokens"]
        G --> H["User grants Intercom to an agent"]
        H --> I["Agent requests tool in a room"]
        I --> J["Session host checks active grant"]
        J -->|Denied| K["Block access"]
        J -->|Allowed| L["Core provides or refreshes token"]
        L --> M["Session-host MCP proxy calls Intercom over HTTPS"]
        M --> N["Return tool result without exposing credentials"]
        N --> J
    
        H -.-> O["Grant disabled or account disconnected"]
        O --> P["Stop access within one minute"]
        P --> Q["Revoke vendor token on disconnect if supported"]
    
    Loading

    Two things I'll verify first

    • Intercom's MCP documentation currently lists conversation reading but does not clearly expose a customer-facing reply tool. I'll verify the live tool list against the issue requirements.
    • Intercom's redirect restrictions and OAuth discovery may need vendor approval or extra compatibility work. I'll discuss any such blocker here before modifying broker logic or weakening security checks.

    I'll keep the PR focused on the existing connector architecture wherever possible.

    Does this approach look good? Happy to take this on! 🚀

  2. wiz-abhi commented on Oct 21, 2026

    @wiz-abhi

    Hi @petr-sandbox @amaudruz — I’d like to take this issue, if it’s still available. I checked the regional and feature requirements against Intercom’s hosted-MCP guide; two checks should gate the implementation rather than be left as post-merge QA.

    Compatibility findings

    • Intercom’s current guide says hosted MCP is supported only for US-hosted workspaces. I would not ship the issue’s EU hostname as supported unless Intercom confirms that has changed.
    • The issue requires replying to conversations. The public guide documents searching/retrieving conversations and contacts but does not establish that the hosted tool list includes a reply action. I would inspect authenticated tools/list and verify a reply on a synthetic conversation before promising this acceptance item.
    • “DCR is documented” does not prove Switch’s redirect is accepted. Verify the protected-resource/authorization metadata for the exact /mcp resource, S256, client registration, and Switch’s callback behavior without relaxing the loader.

    Implementation proposal

    If the server exposes the requested reply tool, add a fixed US endpoint using the generic OAuth/MCP adapter and dynamic registration only after confirming the callback. First validate that the MCP-issued Bearer token satisfies Switch’s identity GET; use a stable Intercom workspace/account identifier, not an agent tool call. Record actual expires_in, refresh-token rotation/reuse and revocation behavior before setting the catalog lifecycle. The skill should search first, quote conversation/contact IDs, avoid implying a reply succeeded until the tool confirms it, and require explicit user intent before sending a reply. If no reply tool or compatible identity flow exists, ask maintainers whether read/search-only scope is acceptable before writing the connector.

    Evidence I’d include

    Loader assertions for the exact endpoint/auth/identity/lifetime fields; OAuth tests for callback, refresh failure and revocation; and a synthetic US workspace room flow covering search/read, an explicitly authorized reply, grant-off within one minute, disconnect, and credential redaction. No authenticated Intercom check has been completed yet.

    I’d resolve reply-tool availability and OAuth identity first, then keep the PR to the catalog, skill, logo attribution and tests—no broker changes unless a measured incompatibility requires an agreed generic fix.

  3. mohitjeswani01 commented on Oct 21, 2026

    @mohitjeswani01

    Hi @petr-sandbox @amaudruz, I'd like to take this one if it's still available.

    I have Switch running locally with FEATURE_FLAGS_ENABLED=service_connections, and since Intercom offers OAuth with dynamic registration, this should follow the catalog/atlassian/ shape (remote MCP + OAuth) with no broker code.

    What I'd verify before writing the entry

    • Loopback sign-in: Intercom only allows localhost redirects without contacting support, so the first thing I'd check is that Console's loopback callback goes through DCR cleanly, with HTTPS and PKCE S256, without loosening any loader checks.
    • Region support: confirm which workspace regions the hosted MCP actually serves before adding the EU endpoint, and only ship what works.
    • Reply tool: check the authenticated tools/list to confirm a conversation reply tool is exposed. If it isn't, I'll flag it here and ask whether read/search-only is acceptable before going further.
    • Identity and token lifetime: confirm the MCP-issued token works for the identity check, and measure the real token lifetime and refresh behavior instead of assuming them.

    Implementation

    • catalog/intercom/connection.yaml with enabled: true, with comments on anything that needs to be turned on in Intercom and anything I measured rather than read in the docs.
    • skill/SKILL.md: search and read conversations and contacts first, quote IDs when referring to them, and require explicit user intent before sending any reply, since replies go to real customers. No mention of credentials.
    • Official Intercom logo (viewBox and paths only), credited in NOTICE.md.

    Testing

    • Loader tests in core/tests/switch_core/connections/test_loader.py for endpoint, auth, identity and lifetime fields.
    • End-to-end on a test workspace with synthetic data: connect → grant → agent reads and replies in a room → grant off within a minute → disconnect. Also check token refresh, and that the token never shows up in the transcript, room or logs.
    • just check, just typecheck and just test, plus the short demo video.

    I'm also following the one-issue-at-a-time rule, so if I end up assigned to another issue first, I'll say so here and step back from this one.

  4. Aditya8369 commented on Oct 22, 2026

    @Aditya8369

    Hey @amaudruz, I would like to contribute to switch repository under the hackathon.

    My Approach:

    1. Overview

    Integrate Intercom as a managed Service Connector using Intercom’s REST/MCP API and Access Tokens. This enables customer support and triage AI agents to search conversations, retrieve contact details, post replies, and manage help desk tickets safely within tenant-isolated environments.


    2. Architecture & Design

    • Connector Type: Service Connection (adapter: api_key or oauth).
    • Protocol: HTTPS REST & Remote MCP tool definitions (https://api.intercom.io).
    • Broker Management: Stores access tokens encrypted at rest; injects Authorization: Bearer {access_token} and required Intercom-Version headers into tool requests at runtime.
    • Agent Skill: Context definition (SKILL.md) outlining conversation search syntax, reply formatting, internal note distinctions, and customer privacy rules.

    3. Authentication & Verification

    • Credential: Extended Access Token generated via the Intercom Developer Hub (or OAuth 2.0 authorization).
    • Identity Check: Validation call to GET https://api.intercom.io/me to retrieve Workspace Name, App ID, Admin ID, and authorized permission scopes.
    • Header Requirements: Injection of Intercom-Version: 2.11 (or latest stable) and standard Bearer token authentication.

    4. Permission Tiers

    Tier Grant Level Permitted Capabilities Prohibited Capabilities
    Tier 1 Read-Only Search contacts, view conversations, inspect tickets, read help articles Sending replies, closing tickets, adding notes
    Tier 2 Support Agent Add internal notes, reply to open conversations, assign conversation tags Deleting records, team reassignment, ticket closure
    Tier 3 Team Lead Close/reopen conversations, reassign teams/inboxes, manage user attributes Destructive data deletion, bulk exports

    5. Implementation Roadmap

    1. Catalog Registration: Add intercom entry in the connection catalog under the Support & CRM category.
    2. Identity Handshake: Implement verification logic against https://api.intercom.io/me with header validation.
    3. Agent Skill Bundle: Create instructions establishing guidelines between public customer replies vs. private internal teammate notes.
    4. UI Integration: Add the Intercom brand icon, connection setup card, and token configuration modal in the console.
    5. PII & Data Safety: Configure redaction filters to mask customer contact details (emails, phone numbers) in system debug logs.
    6. Testing & QA: Verify token expiration handling, rate-limit responses (HTTP 429), inbox assignment routing, and grant revocation flows.

    6. Acceptance Criteria:

    [ ] Register intercom in the Service Connections catalog.
    [ ] Implement Access Token validation against Intercom's identity API (/me).
    [ ] Configure granular permission tiers (Read-only vs. Agent vs. Support Lead).
    [ ] Define the agent skill file (SKILL.md) with conversation response and internal note guardrails.
    [ ] Ensure automated PII protection and sensitive token redaction across logs.
    [ ] Validate end-to-end against an Intercom developer sandbox.

    Could you please assign it to me?

  5. petr-sandbox commented on Oct 22, 2026

    @petr-sandbox
    Collaborator

    Thank you all for your interest and participation in our hackathon! In the interest of fairness, we will not be assigning issues to individual participants but instead let anyone try and solve any number of them.

  6. petr-sandbox commented on Oct 22, 2026

    @petr-sandbox
    Collaborator

    @wiz-abhi thanks for checking. Both points are accepted:

    • US only: don't ship the EU endpoint if Intercom's hosted MCP doesn't serve it. Say "US workspaces only" in the description and skill.
    • No reply tool: if Intercom's MCP really has no conversation-reply tool, a read/search-only v1 is acceptable. Disclose it in the description and the PR. Replying becomes a follow-up.
  7. shanaldo7 commented on Oct 23, 2026

    @shanaldo7

    Hi @amaudruz @petr-sandbox 👋

    I'd like to contribute to Issue #842 — Add the Intercom connector for the Flip the Switch Hackathon.

    My proposed approach:

    1. Verify OAuth compatibility: Review Intercom's official remote MCP server and dynamic client registration documentation, and check compatibility with Switch Console's loopback sign-in flow without introducing new redirect hosts.
    2. Add the connector catalog entry: Create core/switch_core/connections/catalog/intercom/connection.yaml, following the existing connector patterns and service connections v2 design guidelines.
    3. Add the agent skill: Create SKILL.md documenting supported Intercom tasks and tool limitations, with safe defaults such as reading before writing and confirming before closing conversations.
    4. Follow security requirements: Request only the minimum necessary permissions, keep credentials out of agent tools and logs, and document verified vendor-specific limitations.
    5. Add tests and validate: Extend the connection-loader tests and validate the connection and agent-grant flow, including that disabling a grant stops access.

    I'll first inspect the existing connector implementation and contribution guidelines, keeping the change focused unless the documented architecture requires additional work.

    Could you please clarify whether this issue is available for another contributor to work on? I saw the guidance that participants may work without individual assignment and would appreciate confirmation before proceeding.

    Thank you!

  8. Shyam525 commented on Oct 24, 2026

    @Shyam525

    Hi @petr-sandbox @amaudruz, I'm taking a crack at this. Since issues aren't assigned, I'll put a draft PR up within 48h and let verified evidence decide, rather than wait.

    What I'll settle first, with results posted here (redacted) before I write the entry:

    • Discovery: the 401 WWW-Authenticate, protected-resource and authorization-server metadata for /mcp, S256 support, and the registration endpoint.
    • Loopback: that DCR accepts Console's callback (127.0.0.1 and localhost, ephemeral port), with no loader checks loosened.
    • Authenticated tools/list. Intercom's public docs conflict (tool count and region support differ between revisions), so I'll treat the live list as the source of truth, not the docs. If there's no customer-reply tool, I'll ship read/search with the read-only level first, per Petr's note, and say so in the PR and skill. If the server exposes internal notes, I'll treat that as a separate, confirm-first write.
    • Identity: that the MCP-issued token satisfies Switch's identity call with a stable workspace id, plus measured expires_in and refresh behaviour, recorded as comments in connection.yaml.

    PR scope: catalog entry, SKILL.md (region wording, read before write, confirm before any write), loader tests, official logo with NOTICE.md credit, and the demo video (connect, grant, use in a room, grant off, disconnect). No broker changes unless a measured incompatibility needs a generic fix, which I'd raise here first.

  9. gaurav21-05 commented on Oct 28, 2026

    @gaurav21-05

    Hi @amaudruz @petr-sandbox 👋 I'd love to work on this issue. Could you please assign it to me?

    My implementation approach
    Verify OAuth compatibility: Test Intercom's official remote MCP server with Switch Console's loopback login, OAuth discovery, dynamic registration, and PKCE S256. Check US/EU endpoints and redirect restrictions first.
    Add the connector: Create core/switch_core/connections/catalog/intercom/connection.yaml with enabled: true, using the existing Atlassian OAuth + MCP connector as a reference. Configure identity, supported access levels, and token handling.
    Add the skill: Create skill/SKILL.md covering conversation and contact lookups, safe tool usage, read-before-write behavior, and confirmation before sensitive actions.
    Add branding and tests: Include the official Intercom SVG, update the logo NOTICE.md, and extend core/tests/switch_core/connections/test_loader.py.
    End-to-end verification: Test Console connection → agent grant → MCP tool call from a room → grant removal within one minute → disconnect. Also verify token renewal and that credentials never appear in agent context, transcripts, or logs. I'll include a short demo video.
    Proposed architecture

    Two things I'll verify first
    Intercom's MCP documentation currently lists conversation reading but does not clearly expose a customer-facing reply tool. I'll verify the live tool list against the issue requirements.
    Intercom's redirect restrictions and OAuth discovery may need vendor approval or extra compatibility work. I'll discuss any such blocker here before modifying broker logic or weakening security checks.
    I'll keep the PR focused on the existing connector architecture wherever possible.

    Does this approach look good? Happy to take this on! 🚀

  10. 4 remaining items

  11. abhayguptas commented on Oct 29, 2026

    @abhayguptas

    Hey @petr-sandbox @amaudruz, quick update on our verification against a live US Intercom test workspace:

    What’s working cleanly:

    • Auth & Transport: Dynamic client registration, PKCE S256, and Switch Console’s loopback redirect on ports 39231–39235 all work out of the box with https://mcp.intercom.com/mcp.
    • Token Lifecycle: Access tokens live for 1 hour (3,600s), and rotating refresh tokens work as expected.
    • Tool List: The live tools/list returns 20 tools. We confirmed there is no customer-facing reply tool (only search/read, internal notes, help articles, and Fin Operator). We plan to implement the approved read/search-only v1.

    The blocker:

    • Intercom’s MCP tokens are strictly scoped to https://mcp.intercom.com/mcp and are rejected (HTTP 401) by Intercom's REST API at api.intercom.io/me.
    • The MCP server host itself (mcp.intercom.com) doesn’t expose a /me, /user, or OIDC userinfo endpoint.
    • Since Switch’s OAuthAdapter expects a GET endpoint to read an account_id and label, how do you prefer we handle workspace identity for vendors that only offer an MCP server without a REST identity endpoint?
  12. petr-sandbox commented on Oct 29, 2026

    @petr-sandbox
    Collaborator

    Sorry for the contradictory instructions earlier: issues are now assigned to everyone who expressed interest, and the resulting PRs will be reviewed after the hackathon time window. Only one PR will be selected per issue.

  13. AbarnaaSree commented on Oct 29, 2026

    @AbarnaaSree

    Hi @petr-sandbox and @amaudruz 👋

    I’m interested in contributing to the Intercom connector issue (#842) for the Flip the Switch Hackathon. I’ve reviewed the issue and would like to work on it.

    Could you please confirm whether I can proceed with this issue? Thank you!

  14. petr-sandbox commented on Oct 30, 2026

    @petr-sandbox
    Collaborator

    @AbarnaaSree thanks for your interest. To spread contributors across issues, we've assigned you to five issues with fewer participants: #808, #806, #785, #807 and #782. Please focus on those.

  15. marripudi-amrutha02 commented on Nov 2, 2026

    @marripudi-amrutha02

    Hi @petr-sandbox @amaudruz, I would like to work on this Intercom connector.

    I am solo participant from India (Bhimavaram), building C-Buddy - AI study buddy for CSE students using Switch + Telegram.

    My plan: I will add Intercom connector following existing connector pattern (like Zendesk example), starting with basic client and webhook.

    Please assign #842 to me. My fork: marripudi-amrutha02/switch

    Thank you!

  16. Mamtasahu2005 commented on Nov 3, 2026

    @Mamtasahu2005

    Hi @petr-sandbox, I would like to work on adding the Intercom connector!

    My plan:

    1. Follow the existing connector specifications in the repo.
    2. Implement Intercom API authentication, conversation fetching, and message posting schemas.
    3. Verify functionality locally with Switch rooms.
    4. Submit a clean PR referencing this issue.

    Could you please assign this to me? Thanks!

  17. marripudi-amrutha02 commented on Nov 3, 2026

    @marripudi-amrutha02

    Hi, I checked PR #1141 which fixes this. I tested the Intercom connector locally. It connects to mcp.intercom.com via OAuth and can search conversations/contacts. Looks good to merge. Can I help with testing/docs?

  18. Meet-4 commented on Nov 3, 2026

    @Meet-4
    Contributor

    Taking #842 (Intercom) for the hackathon, as a remote-MCP + OAuth entry with dynamic registration.

    Verified live, not just from the docs:

    • GET https://mcp.intercom.com/mcp → 401 challenge with resource_metadata pointing at /.well-known/oauth-protected-resource → resource https://mcp.intercom.com, authorization server https://mcp.intercom.com, scopes [mcp, operator].
    • /.well-known/oauth-authorization-server → authorization_endpoint /authorize, token_endpoint /token, registration_endpoint /register, revocation_endpoint /token, grant_types [authorization_code, refresh_token], token_endpoint_auth_methods [client_secret_basic, client_secret_post, none], code_challenge_methods [S256] — a public client with PKCE and a refresh grant, like Atlassian's.
    • DCR works for real: POST /register with the loopback redirect http://127.0.0.1:39231/callback and token_endpoint_auth_method: none returned 201 with a client_id and the refresh_token grant intact. So registration: dynamic, redirect: [loopback], no operator app — the issue's own "check that Switch Console's loopback sign-in works" holds: my probe used exactly Console's loopback shape.

    Shape of the entry:

    • mcp.servers: https://mcp.intercom.com/mcp (US). The EU host is https://mcp.eu.intercom.com/mcp with its own issuer; the catalog has one entry per server, so EU needs its own entry or a host-choosing field the catalog does not have today — I will say so in the PR rather than invent one.
    • Scopes: Intercom's AS advertises exactly two, mcp and operator. mcp is the whole standard surface (the 14 tools, including the ones that write: add_internal_note, article create/update); operator is the Fin Operator tier, which "only appear[s] for workspaces that have Fin Operator". So read = [mcp], and the write level adds operator — Intercom has no read-only scope, and I will say that plainly: a read grant can still add an internal note, and the skill carries the confirm-before-writing rule as the guard.
    • Identity: GET https://api.intercom.com/me with the Bearer token, id → account_id, email → label — Intercom's documented admin endpoint, and a GET as the catalog requires. Whether Intercom's MCP-issued token is accepted there is the one thing I cannot verify without a workspace; if it is not, the honest fallback is an api_key entry (Intercom's MCP also accepts a plain Bearer API token, and those do work on /me), and I will note that in the PR.

    PR follows with the entry, the skill, and loader-test updates (placeholder set, enabled list, a shipped-entry test).

  19. marripudi-amrutha02 commented on Nov 3, 2026

    @marripudi-amrutha02

    Hi team, verified PR #1141 already implements Intercom remote MCP + OAuth with DCR.
    I tested the flow as per issue. Happy to help with docs/testing for C-Buddy use case.
    My fork: marripudi-amrutha02/switch

  20. goodchanges commented on Nov 6, 2026

    @goodchanges

    Can I work on this issue @amaudruz

  21. petr-sandbox commented on Nov 6, 2026

    @petr-sandbox
    Collaborator

    @goodchanges this issue has reached GitHub's limit of 10 assignees, so I couldn't add you. You don't need to be assigned to work on it, and a PR from you counts the same.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions