Repository navigation
Description
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:
- a remote MCP server with OAuth (example:
catalog/atlassian/) - a command-line tool with OAuth (example:
catalog/google-workspace/) - a key the person pastes in (
adapter: api_key, withmcporcli; 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.yamlis complete andenabled: true, with comments on anything the vendor needs turned on and anything measured rather than documented (e.g. token lifetime) -
skill/SKILL.mddescribes 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
ANAMASGARD commentedon Oct 21, 2026
Hi @amaudruz @petr-sandbox 👋 I'd love to work on this issue. Could you please assign it to me?
My implementation approach
core/switch_core/connections/catalog/intercom/connection.yamlwithenabled: true, using the existing Atlassian OAuth + MCP connector as a reference. Configure identity, supported access levels, and token handling.skill/SKILL.mdcovering conversation and contact lookups, safe tool usage, read-before-write behavior, and confirmation before sensitive actions.NOTICE.md, and extendcore/tests/switch_core/connections/test_loader.py.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"]Two things I'll verify first
I'll keep the PR focused on the existing connector architecture wherever possible.
Does this approach look good? Happy to take this on! 🚀
wiz-abhi commentedon Oct 21, 2026
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
tools/listand verify a reply on a synthetic conversation before promising this acceptance item./mcpresource, 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.
mohitjeswani01 commentedon Oct 21, 2026
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 thecatalog/atlassian/shape (remote MCP + OAuth) with no broker code.What I'd verify before writing the entry
tools/listto 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.Implementation
catalog/intercom/connection.yamlwithenabled: 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.viewBoxand paths only), credited inNOTICE.md.Testing
core/tests/switch_core/connections/test_loader.pyfor endpoint, auth, identity and lifetime fields.just check,just typecheckandjust 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.
Aditya8369 commentedon Oct 22, 2026
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
adapter: api_keyoroauth).https://api.intercom.io).Authorization: Bearer {access_token}and requiredIntercom-Versionheaders into tool requests at runtime.SKILL.md) outlining conversation search syntax, reply formatting, internal note distinctions, and customer privacy rules.3. Authentication & Verification
GET https://api.intercom.io/meto retrieve Workspace Name, App ID, Admin ID, and authorized permission scopes.Intercom-Version: 2.11(or latest stable) and standard Bearer token authentication.4. Permission Tiers
5. Implementation Roadmap
intercomentry in the connection catalog under the Support & CRM category.https://api.intercom.io/mewith header validation.6. Acceptance Criteria:
[ ] Register
intercomin 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?
petr-sandbox commentedon Oct 22, 2026
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.
petr-sandbox commentedon Oct 22, 2026
@wiz-abhi thanks for checking. Both points are accepted:
shanaldo7 commentedon Oct 23, 2026
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:
core/switch_core/connections/catalog/intercom/connection.yaml, following the existing connector patterns and service connections v2 design guidelines.SKILL.mddocumenting supported Intercom tasks and tool limitations, with safe defaults such as reading before writing and confirming before closing conversations.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!
Shyam525 commentedon Oct 24, 2026
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:
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.
gaurav21-05 commentedon Oct 28, 2026
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! 🚀
4 remaining items
abhayguptas commentedon Oct 29, 2026
Hey @petr-sandbox @amaudruz, quick update on our verification against a live US Intercom test workspace:
What’s working cleanly:
https://mcp.intercom.com/mcp.tools/listreturns 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:
https://mcp.intercom.com/mcpand are rejected (HTTP 401) by Intercom's REST API atapi.intercom.io/me.mcp.intercom.com) doesn’t expose a/me,/user, or OIDC userinfo endpoint.OAuthAdapterexpects a GET endpoint to read anaccount_idand label, how do you prefer we handle workspace identity for vendors that only offer an MCP server without a REST identity endpoint?petr-sandbox commentedon Oct 29, 2026
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.
AbarnaaSree commentedon Oct 29, 2026
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!
petr-sandbox commentedon Oct 30, 2026
@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.
marripudi-amrutha02 commentedon Nov 2, 2026
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!
Mamtasahu2005 commentedon Nov 3, 2026
Hi @petr-sandbox, I would like to work on adding the Intercom connector!
My plan:
Could you please assign this to me? Thanks!
marripudi-amrutha02 commentedon Nov 3, 2026
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?
Meet-4 commentedon Nov 3, 2026
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 withresource_metadatapointing at/.well-known/oauth-protected-resource→ resourcehttps://mcp.intercom.com, authorization serverhttps://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.POST /registerwith the loopback redirecthttp://127.0.0.1:39231/callbackandtoken_endpoint_auth_method: nonereturned 201 with aclient_idand therefresh_tokengrant intact. Soregistration: 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 ishttps://mcp.eu.intercom.com/mcpwith 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.mcpandoperator.mcpis the whole standard surface (the 14 tools, including the ones that write:add_internal_note, article create/update);operatoris the Fin Operator tier, which "only appear[s] for workspaces that have Fin Operator". So read =[mcp], and the write level addsoperator— 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.GET https://api.intercom.com/mewith 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 anapi_keyentry (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).
marripudi-amrutha02 commentedon Nov 3, 2026
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
goodchanges commentedon Nov 6, 2026
Can I work on this issue @amaudruz
petr-sandbox commentedon Nov 6, 2026
@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.