Create Intercom Setup Docs

[svadrutk]

What this covers. How to connect a Speakeasy-hosted Intercom MCP server to Intercom's OAuth, by manually registering an Intercom app. Use this when a customer wants Intercom in their MCP catalog. Written to be reusable across customers — substitute your own org, project, and server values where noted.

Background — why manual registration is needed

Intercom's authorization server does not support full Dynamic Client Registration (DCR). When Speakeasy attempts DCR against Intercom, the registration is rejected because Speakeasy's callback domain is not on Intercom's redirect-URI allowlist. The error directs you to contact Intercom support if you believe the domain should be supported.

There are two ways forward:

1. Ask Intercom to allowlist Speakeasy's redirect URI (unblocks DCR). Slower — depends on Intercom support. See Option B.
2. Manually register an Intercom app and attach it as an OAuth provider in Speakeasy. This is the tested, self-serve path and the recommended default. See Option A.

An Intercom admin is required either way.

---

Option A — Manually register an Intercom app (recommended)

Part 1: In Intercom

1. Create a new app in the Intercom Developer Hub (https://app.intercom.com/a/apps/<your-workspace>/developer-hub). See Intercom's Create an app and Setting up OAuth docs.

2. Open Authentication, click Edit (top right), check Enable OAuth, and add the callback URL:

   <https://app.getgram.ai/mcp/remote_login_callback>
   

3. Set permissions. A broad set is selected by default — the simplest choice is to keep the defaults. To constrain them, the minimum required permissions are:

   • Read and list users and companies
   • Read conversations
   • Read one admin
   • Read and list articles

   You may uncheck everything else.

4. Return to Basic Information and record the Client ID and Client Secret — you'll enter these in Speakeasy.

Part 2: In Speakeasy

1. Go to the Intercom server's Settings → Authentication page:

   <https://app.getgram.ai/><org>/projects/<project>/mcp/x/<intercom-server-slug>/settings#authentication
   

2. Click Attach Provider → Add New and enter:

Field	Value
Issuer URL	https://mcp.intercom.com
Authorization Endpoint	https://app.intercom.com/oauth
Token Endpoint	https://api.intercom.io/auth/eagle/token
Client ID	(from Intercom, Part 1 step 4)
Client Secret	(from Intercom, Part 1 step 4)

Minimum Intercom permissions: Read and list users and companies · Read conversations · Read one admin · Read and list articles.

---

Troubleshooting

"Toolset missing" when opening the server. The server version may have failed to sync with the customer's plugin. Re-check/fix the plugin version on the Speakeasy side. Whether the customer picks up the update automatically depends on their distribution method:

• GitHub integration: plugin re-syncs automatically; no manual step.
• Manual zip upload: the customer must re-upload their plugin zip to pick up the new version.

---

Intercom's OAuth endpoints and permission model can change — verify against the Intercom developer docs if a step doesn't match what you see.

> **What this covers.** How to connect a Speakeasy-hosted Intercom MCP server to Intercom's OAuth, by manually registering an Intercom app. Use this when a customer wants Intercom in their MCP catalog. Written to be reusable across customers — substitute your own org, project, and server values where noted. >

Background — why manual registration is needed

Intercom's authorization server does not support full Dynamic Client Registration (DCR). When Speakeasy attempts DCR against Intercom, the registration is rejected because Speakeasy's callback domain is not on Intercom's redirect-URI allowlist. The error directs you to contact Intercom support if you believe the domain should be supported.

There are two ways forward:

1. Ask Intercom to allowlist Speakeasy's redirect URI (unblocks DCR). Slower — depends on Intercom support. See Option B.
2. Manually register an Intercom app and attach it as an OAuth provider in Speakeasy. This is the tested, self-serve path and the recommended default. See Option A.

An Intercom admin is required either way.

---

Option A — Manually register an Intercom app (recommended)

Part 1: In Intercom

1. Create a new app in the Intercom Developer Hub (https://app.intercom.com/a/apps/<your-workspace>/developer-hub). See Intercom's Create an app and Setting up OAuth docs.

   !CleanShot 2026-07-07 at 20.56.08@2x.png

2. Open Authentication, click Edit (top right), check Enable OAuth, and add the callback URL:

   https://app.getgram.ai/mcp/remote_login_callback
   

   !CleanShot 2026-07-07 at 21.01.37@2x.png

3. Set permissions. A broad set is selected by default — the simplest choice is to keep the defaults. To constrain them, the minimum required permissions are:

   • Read and list users and companies
   • Read conversations
   • Read one admin
   • Read and list articles

   You may uncheck everything else.

4. Return to Basic Information and record the Client ID and Client Secret — you'll enter these in Speakeasy.

   !CleanShot 2026-07-07 at 21.16.14@2x.png

Part 2: In Speakeasy

1. Go to the Intercom server's Settings → Authentication page:

   https://app.getgram.ai/<org>/projects/<project>/mcp/x/<intercom-server-slug>/settings#authentication
   

2. Click Attach Provider → Add New and enter:

Field	Value
Issuer URL	https://mcp.intercom.com
Authorization Endpoint	https://app.intercom.com/oauth
Token Endpoint	https://api.intercom.io/auth/eagle/token
Client ID	(from Intercom, Part 1 step 4)
Client Secret	(from Intercom, Part 1 step 4)

1. Accept the default values for the remaining fields and save.

That's it — the MCP server should now be connectable.

---

Option B — Request redirect-URI allowlisting from Intercom {#option-b}

If you'd rather have Intercom support the DCR path, reach out to your Intercom contact and ask them to allowlist Speakeasy's redirect URI. Sample outreach:

We're trying to connect to your MCP server via a platform we use (called Speakeasy).

When Speakeasy's platform attempts dynamic client registration with your authorization server, the registration is rejected because its callback domain isn't on your redirect-URI allowlist. The error message directs us to contact Intercom support if we believe the domain should be supported — so we're reaching out.

Could you please add the following redirect URI to your allowlist: https://app.getgram.ai/mcp/remote_login_callback

Happy to provide more details if helpful. Thanks!

---

Reference values

Item	Value
Speakeasy redirect / callback URI	https://app.getgram.ai/mcp/remote_login_callback
Intercom Issuer URL	https://mcp.intercom.com
Intercom Authorization Endpoint	https://app.intercom.com/oauth
Intercom Token Endpoint	https://api.intercom.io/auth/eagle/token

Minimum Intercom permissions: Read and list users and companies · Read conversations · Read one admin · Read and list articles.

---

Troubleshooting

"Toolset missing" when opening the server. The server version may have failed to sync with the customer's plugin. Re-check/fix the plugin version on the Speakeasy side. Whether the customer picks up the update automatically depends on their distribution method:

• GitHub integration: plugin re-syncs automatically; no manual step.
• Manual zip upload: the customer must re-upload their plugin zip to pick up the new version.

---

Intercom's OAuth endpoints and permission model can change — verify against the Intercom developer docs if a step doesn't match what you see.

[walker-tx]

Resolved as intercom (Intercom), persona it-admin.

Notes handed to the pipeline:

Manual Intercom Developer Hub OAuth app (recommended); DCR fails without redirect allowlist. Callback: https://app.getgram.ai/mcp/remote_login_callback. Attach provider in Speakeasy: issuer https://mcp.intercom.com, auth https://app.intercom.com/oauth, token https://api.intercom.io/auth/eagle/token. Min scopes: users/companies read+list, conversations read, one admin read, articles read+list. Option B: ask Intercom to allowlist callback for DCR. Docs: https://developers.intercom.com/docs/build-an-integration/learn-more/authentication/setting-up-oauth

Starting draft-guide…

[walker-tx]

Pipeline review (intercom)

Outcome: Reviewers passed after 2 round(s). Still skim the open questions below before merging.

Draft PR: #59

Open questions (3)

Research could not prove these from public docs. Check the boxes by replying with answers, or say “unknown / omit”. Silence + an existing hedge in the guide usually means omit / keep hedge — not a console capture.

• Intercom does not publish its authorization-screen sequence or exact approval-button labels.
• Intercom does not name the OAuth page control that persists changes.
• Intercom does not publish the DCR callback-allowlisting process, eligibility rules, or turnaround time.

Optional nits (1)

• connect-speakeasy-credentials, steps 5–6: The authorization and token endpoint fields are not identified by exact UI labels. → Record this canonical UI-label gap for human doctrine review, then render the exact labels once established.

How to retry

1. Reply on this issue using the Decision N: … lines above (and answer open questions).
2. Re-add the guide:draft label. Distill reads the issue body and comments into pipeline notes.
3. If a factory draft PR already exists (guide/issue-<N>-*), the next run resumes on that branch and revises prior research/setup instead of starting blank.

Source: run-record.json