From 5800b3b7579548bebecd58b4f199059309326db3 Mon Sep 17 00:00:00 2001 From: "guide-factory[bot]" Date: Tue, 18 Aug 2026 20:29:22 +0000 Subject: [PATCH] Draft guide: intercom (issue #158) --- guides/intercom/meta.yaml | 32 +++---- guides/intercom/pipeline.lock.json | 92 +++++++++---------- guides/intercom/research.md | 86 ++++++++--------- guides/intercom/speakeasy.md | 22 ++--- retro/runs/2026-08-18T20:24:38Z-intercom.json | 61 ++++++++++++ 5 files changed, 163 insertions(+), 130 deletions(-) create mode 100644 retro/runs/2026-08-18T20:24:38Z-intercom.json diff --git a/guides/intercom/meta.yaml b/guides/intercom/meta.yaml index 901c5ea..60eb70b 100644 --- a/guides/intercom/meta.yaml +++ b/guides/intercom/meta.yaml @@ -40,11 +40,11 @@ remotes: locator: https://developers.intercom.com/docs/guides/mcp name: Model Context Protocol (MCP) classification: official - observed_at: "2026-07-29T15:06:51Z" + observed_at: "2026-08-18T20:24:38Z" - source: operator-validation locator: draft-guide operator notes for intercom status: manual OAuth validated - observed_at: "2026-07-29T15:06:51Z" + observed_at: "2026-08-18T20:24:38Z" - id: eu url: https://mcp.eu.intercom.com/mcp transport: streamable-http @@ -56,62 +56,58 @@ remotes: locator: https://developers.intercom.com/docs/guides/mcp name: Model Context Protocol (MCP) classification: official - observed_at: "2026-07-29T15:06:51Z" - - source: operator-validation - locator: draft-guide operator notes for intercom - status: manual OAuth validated - observed_at: "2026-07-29T15:06:51Z" + observed_at: "2026-08-18T20:24:38Z" provenance: - source: provider-documentation locator: https://developers.intercom.com/docs/guides/mcp name: Model Context Protocol (MCP) classification: official - observed_at: "2026-07-29T15:06:51Z" + observed_at: "2026-08-18T20:24:38Z" - source: provider-documentation locator: https://developers.intercom.com/docs/build-an-integration/getting-started name: Set up a Workspace classification: official - observed_at: "2026-07-29T15:06:51Z" + observed_at: "2026-08-18T20:24:38Z" - source: provider-documentation locator: https://developers.intercom.com/docs/build-an-integration/learn-more/authentication/setting-up-oauth name: Setting up OAuth classification: official - observed_at: "2026-07-29T15:06:51Z" + observed_at: "2026-08-18T20:24:38Z" - source: provider-documentation locator: https://developers.intercom.com/docs/build-an-integration/learn-more/authentication/oauth-scopes name: OAuth Scopes classification: official - observed_at: "2026-07-29T15:06:51Z" + observed_at: "2026-08-18T20:24:38Z" - source: provider-documentation locator: https://developers.intercom.com/docs/build-an-integration/learn-more/authentication name: Authentication classification: official - observed_at: "2026-07-29T15:06:51Z" + observed_at: "2026-08-18T20:24:38Z" - source: provider-documentation locator: https://developers.intercom.com/llms.txt name: Intercom developer documentation index classification: official - observed_at: "2026-07-29T15:06:51Z" + observed_at: "2026-08-18T20:24:38Z" - source: provider-documentation locator: https://www.intercom.com/help/en/articles/6124430-regional-data-hosting name: Regional Data Hosting classification: official - observed_at: "2026-07-29T15:06:51Z" + observed_at: "2026-08-18T20:24:38Z" - source: endpoint-observation locator: https://app.intercom.com/admins/sign_in name: Intercom sign-in page classification: official - observed_at: "2026-07-29T15:06:51Z" + observed_at: "2026-08-18T20:24:38Z" - source: endpoint-observation locator: https://mcp.intercom.com/.well-known/oauth-authorization-server classification: official - observed_at: "2026-07-29T15:06:51Z" + observed_at: "2026-08-18T20:24:38Z" - source: operator-validation locator: draft-guide operator notes for intercom status: manual OAuth recommended; DCR requires callback allowlisting - observed_at: "2026-07-29T15:06:51Z" + observed_at: "2026-08-18T20:24:38Z" - source: repository-doctrine locator: doctrine/speakeasy-setup.md name: Speakeasy setup canonical section classification: official - observed_at: "2026-07-29T15:06:51Z" + observed_at: "2026-08-18T20:24:38Z" diff --git a/guides/intercom/pipeline.lock.json b/guides/intercom/pipeline.lock.json index a5444e4..0fb0e6f 100644 --- a/guides/intercom/pipeline.lock.json +++ b/guides/intercom/pipeline.lock.json @@ -2,14 +2,14 @@ "schema_version": 1, "slug": "intercom", "persona": "it-admin", - "runtime": "cursor-sdk", - "updated_at": "2026-07-29T15:15:59Z", + "runtime": "pi", + "updated_at": "2026-08-18T20:29:21Z", "steps": { "research": { - "input_digest": "sha256:6e304ac36ef5fa89975820896e4504a53a2f7f0f33a7467084c29cfe7c2ec33d", + "input_digest": "sha256:cacdc0ca267cfe2221dd7d06b8fe3f986b63bb91e61fa24792bf730876deed7b", "inputs": { - "model": "gpt-5.6-sol", - "prompt_digest": "sha256:3b79ac335ee0b509b454301f3d8eb1d9665aea3729404aa00d65e08433e6b4e5", + "model": "openrouter/openai/gpt-5.6-sol", + "prompt_digest": "sha256:255c60266361ff6711b0b04829329485020218f5a0460f70aa30f30d9c1711fc", "reading_list": [ { "path": "doctrine/glossary.md", @@ -21,36 +21,36 @@ }, { "path": "doctrine/roles/technical-research.md", - "digest": "sha256:f82583e4ba9e92f061b09e6685b3a2640a1826f6fbc27ddac52e0db68387acaf" + "digest": "sha256:88f093f873c705128a0a31eb38be298a2ee11f4d50815552739925337f8ac3ad" }, { "path": "doctrine/speakeasy-setup.md", - "digest": "sha256:8715948a90f95187a2e093e3dfbaccb2870423ee7c90aed4eeba5c418c0bb85e" + "digest": "sha256:9f173facc7f63e450eb7e4d693c67c0a88e9ff68f0a381cfcbae413a8d47dd16" } ], "artifacts": [], "params": { "provider": "intercom", - "notes": "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\n\nSpeakeasy MCP Catalog: overridden-tenanted" + "notes": "Refresh the existing guide to match its lockfile; runtime: cursor-sdk; last locked: 2026-07-29T15:15:59Z.\n\nSpeakeasy MCP Catalog: overridden-tenanted" } }, "outputs": [ { "path": "research.md", - "digest": "sha256:c3bfaadb51be5575c5821a2f08e04b9eeb67394a1c35227485a45191ea3bfd91" + "digest": "sha256:8676e4b6816cf55e27284600d616f65e6a84a0b652632beff0f603085bb51fce" }, { "path": "meta.yaml", - "digest": "sha256:071b0fee3b30edcf251da79d7d4b104c51141ed9967170e4e26ec73952b953f2" + "digest": "sha256:f529b8f50f193626fefe0ba5235542205b50ed1d059e4c5146edd2f34003b55c" } ], - "completed_at": "2026-07-29T15:15:59Z" + "completed_at": "2026-08-18T20:29:21Z" }, "draft": { - "input_digest": "sha256:04c63eed17b390d2d47b469dee79b55092b6be3a19f5e5fa93a42fa7e597cd23", + "input_digest": "sha256:234784a69b2a6914c934556218a624557a7a62c5c662800870686897536870e5", "inputs": { - "model": "gpt-5.6-sol", - "prompt_digest": "sha256:bd455424d5c087fd914297fad0cf7749459452dbd94d00bd4e20e977e9fbb92b", + "model": "openrouter/openai/gpt-5.6-sol", + "prompt_digest": "sha256:ad649d12e8bf3882a1593555c0c4d31681ac50aa891177b1a8f766a563d85d6c", "reading_list": [ { "path": "doctrine/glossary.md", @@ -62,46 +62,46 @@ }, { "path": "doctrine/roles/writer.md", - "digest": "sha256:7b88b10bd5ce607985054abbdce5e6b742acc7074c1461f08d34321523e17799" + "digest": "sha256:4214af68feea7dfc68fab1058e1d5d35e6238d5b51fd9b10db421ebafc49a3cc" }, { "path": "doctrine/personas/it-admin.md", - "digest": "sha256:b76dc61236fa5c56390354a0d51d5b5ee666395bb65a2e993b79bd9aa9c1fd0d" + "digest": "sha256:38c1356b43c9e5f92527f9b73e8561a62cb2eb636b675796af49d0b6015dd9be" } ], "artifacts": [ { "path": "research.md", - "digest": "sha256:c3bfaadb51be5575c5821a2f08e04b9eeb67394a1c35227485a45191ea3bfd91" + "digest": "sha256:8676e4b6816cf55e27284600d616f65e6a84a0b652632beff0f603085bb51fce" }, { "path": "meta.yaml", - "digest": "sha256:071b0fee3b30edcf251da79d7d4b104c51141ed9967170e4e26ec73952b953f2" + "digest": "sha256:f529b8f50f193626fefe0ba5235542205b50ed1d059e4c5146edd2f34003b55c" } ], "params": { "provider": "intercom", - "notes": "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\n\nSpeakeasy MCP Catalog: overridden-tenanted", + "notes": "Refresh the existing guide to match its lockfile; runtime: cursor-sdk; last locked: 2026-07-29T15:15:59Z.\n\nSpeakeasy MCP Catalog: overridden-tenanted", "persona": "it-admin" } }, "outputs": [ { "path": "external.md", - "digest": "sha256:2b8ea05a45dbf45d45573755807ab19d9d23de0a4447798d84bc18673a80ae0f" + "digest": "sha256:aa58b602c65e28178f606388c2d3d17c14eab1a8e9c4e6dab68fe2a7f03898e1" }, { "path": "speakeasy.md", - "digest": "sha256:062bfa48925435cff15b96a7e1a2c9c207b215e0d74675696e7f1d8cdc679889" + "digest": "sha256:056cff5ab0c29fffe05cedb978c8a09ba4fe52456022dcb5f090e8ef2b1dd8a3" } ], - "completed_at": "2026-07-29T15:15:59Z" + "completed_at": "2026-08-18T20:29:21Z" }, "review.fidelity": { - "input_digest": "sha256:3c91cc5b556b2b46bdb54294e6d305e843ec4820595f2ba92970e362fc202f06", + "input_digest": "sha256:1ea519b0af4d4071d01cf5f5dec1cdcadb9dc6ca20bad74704780b99f7dd359a", "inputs": { - "model": "gpt-5.6-sol", - "prompt_digest": "sha256:cb91cacc0c50621e5c913643f99937071ea75c9a7c0856ff8c6cc70fc568d861", + "model": "openrouter/openai/gpt-5.6-sol", + "prompt_digest": "sha256:2885ba720bba92fbed782f1ac13fdbd065c3f1a294302ee85792fc4f61866e1f", "reading_list": [ { "path": "doctrine/glossary.md", @@ -113,30 +113,30 @@ }, { "path": "doctrine/roles/fidelity.md", - "digest": "sha256:472ec8a2db648c822d126dea857d3f79e9c97a8e9b5fe6a997170bef3c8d2c22" + "digest": "sha256:f1c64906d2702d25c5db118f0a1a471b4962333a506c235ffebccf67413aa7f3" } ], "artifacts": [ { "path": "research.md", - "digest": "sha256:c3bfaadb51be5575c5821a2f08e04b9eeb67394a1c35227485a45191ea3bfd91" + "digest": "sha256:8676e4b6816cf55e27284600d616f65e6a84a0b652632beff0f603085bb51fce" }, { "path": "meta.yaml", - "digest": "sha256:071b0fee3b30edcf251da79d7d4b104c51141ed9967170e4e26ec73952b953f2" + "digest": "sha256:f529b8f50f193626fefe0ba5235542205b50ed1d059e4c5146edd2f34003b55c" }, { "path": "external.md", - "digest": "sha256:2b8ea05a45dbf45d45573755807ab19d9d23de0a4447798d84bc18673a80ae0f" + "digest": "sha256:aa58b602c65e28178f606388c2d3d17c14eab1a8e9c4e6dab68fe2a7f03898e1" }, { "path": "speakeasy.md", - "digest": "sha256:062bfa48925435cff15b96a7e1a2c9c207b215e0d74675696e7f1d8cdc679889" + "digest": "sha256:056cff5ab0c29fffe05cedb978c8a09ba4fe52456022dcb5f090e8ef2b1dd8a3" } ], "params": { "provider": "intercom", - "notes": "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\n\nSpeakeasy MCP Catalog: overridden-tenanted", + "notes": "Refresh the existing guide to match its lockfile; runtime: cursor-sdk; last locked: 2026-07-29T15:15:59Z.\n\nSpeakeasy MCP Catalog: overridden-tenanted", "persona": "it-admin", "dimension": "fidelity" } @@ -144,20 +144,20 @@ "outputs": [ { "path": "external.md", - "digest": "sha256:2b8ea05a45dbf45d45573755807ab19d9d23de0a4447798d84bc18673a80ae0f" + "digest": "sha256:aa58b602c65e28178f606388c2d3d17c14eab1a8e9c4e6dab68fe2a7f03898e1" }, { "path": "speakeasy.md", - "digest": "sha256:062bfa48925435cff15b96a7e1a2c9c207b215e0d74675696e7f1d8cdc679889" + "digest": "sha256:056cff5ab0c29fffe05cedb978c8a09ba4fe52456022dcb5f090e8ef2b1dd8a3" } ], - "completed_at": "2026-07-29T15:15:59Z" + "completed_at": "2026-08-18T20:29:21Z" }, "review.achievability": { - "input_digest": "sha256:85247bea46b2cccffcd67c772613725fc8fe103e478be89341a990d1c08f4335", + "input_digest": "sha256:ce37650f89d13b9eb36f9e5d264f9b47918d3d49ba0b7af0d09855d5325e85dd", "inputs": { - "model": "gpt-5.6-sol", - "prompt_digest": "sha256:5da0cf6dfcf7d6cc8a083825cd048f87c4d0ce7442683b67981efb98b8a97ca3", + "model": "openrouter/openai/gpt-5.6-sol", + "prompt_digest": "sha256:0b287f892ece7611416030973e4b1952db4c173e3023930bf238685d39b79cdf", "reading_list": [ { "path": "doctrine/glossary.md", @@ -173,30 +173,30 @@ }, { "path": "doctrine/personas/it-admin.md", - "digest": "sha256:b76dc61236fa5c56390354a0d51d5b5ee666395bb65a2e993b79bd9aa9c1fd0d" + "digest": "sha256:38c1356b43c9e5f92527f9b73e8561a62cb2eb636b675796af49d0b6015dd9be" } ], "artifacts": [ { "path": "research.md", - "digest": "sha256:c3bfaadb51be5575c5821a2f08e04b9eeb67394a1c35227485a45191ea3bfd91" + "digest": "sha256:8676e4b6816cf55e27284600d616f65e6a84a0b652632beff0f603085bb51fce" }, { "path": "meta.yaml", - "digest": "sha256:071b0fee3b30edcf251da79d7d4b104c51141ed9967170e4e26ec73952b953f2" + "digest": "sha256:f529b8f50f193626fefe0ba5235542205b50ed1d059e4c5146edd2f34003b55c" }, { "path": "external.md", - "digest": "sha256:2b8ea05a45dbf45d45573755807ab19d9d23de0a4447798d84bc18673a80ae0f" + "digest": "sha256:aa58b602c65e28178f606388c2d3d17c14eab1a8e9c4e6dab68fe2a7f03898e1" }, { "path": "speakeasy.md", - "digest": "sha256:062bfa48925435cff15b96a7e1a2c9c207b215e0d74675696e7f1d8cdc679889" + "digest": "sha256:056cff5ab0c29fffe05cedb978c8a09ba4fe52456022dcb5f090e8ef2b1dd8a3" } ], "params": { "provider": "intercom", - "notes": "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\n\nSpeakeasy MCP Catalog: overridden-tenanted", + "notes": "Refresh the existing guide to match its lockfile; runtime: cursor-sdk; last locked: 2026-07-29T15:15:59Z.\n\nSpeakeasy MCP Catalog: overridden-tenanted", "persona": "it-admin", "dimension": "achievability" } @@ -204,14 +204,14 @@ "outputs": [ { "path": "external.md", - "digest": "sha256:2b8ea05a45dbf45d45573755807ab19d9d23de0a4447798d84bc18673a80ae0f" + "digest": "sha256:aa58b602c65e28178f606388c2d3d17c14eab1a8e9c4e6dab68fe2a7f03898e1" }, { "path": "speakeasy.md", - "digest": "sha256:062bfa48925435cff15b96a7e1a2c9c207b215e0d74675696e7f1d8cdc679889" + "digest": "sha256:056cff5ab0c29fffe05cedb978c8a09ba4fe52456022dcb5f090e8ef2b1dd8a3" } ], - "completed_at": "2026-07-29T15:15:59Z" + "completed_at": "2026-08-18T20:29:21Z" } } } diff --git a/guides/intercom/research.md b/guides/intercom/research.md index 8b2296f..6b0f451 100644 --- a/guides/intercom/research.md +++ b/guides/intercom/research.md @@ -1,7 +1,7 @@ --- research_version: 1 slug: intercom -researched_at: 2026-07-29T15:06:51Z +researched_at: 2026-08-18T20:24:38Z --- # Intercom — Research Dossier @@ -32,13 +32,8 @@ is rendered. recommended over its deprecated SSE URLs. - **Authentication Option documented by this Guide:** OAuth with a pre-registered Intercom Developer Hub app. The Speakeasy AI Control Plane - receives the app's **Client ID** and **Client secret** and uses: - - Issuer URL: `https://mcp.intercom.com` - - Authorization endpoint: `https://app.intercom.com/oauth` - - Token endpoint: `https://api.intercom.io/auth/eagle/token` - The issuer and endpoint combination was validated by the operator for the - manual attachment flow. Intercom's OAuth guide independently documents the - US authorization endpoint and Eagle token endpoint. + receives the app's **Client ID** and **Client secret**. The US manual + attachment flow was validated by the operator. - **Why manual registration is recommended:** Intercom's live MCP authorization-server metadata advertises a DCR endpoint, but the operator observed that registration fails unless Intercom has allowlisted the @@ -90,9 +85,6 @@ Information** page. | Client ID | Intercom Developer Hub app, **Basic Information** ({#copy-client-credentials}) | | Client Secret (optional) | Intercom Developer Hub app, **Basic Information** ({#copy-client-credentials}) | | Redirect URI registered with Intercom | `{{ gram.oauth.callback_url }}` in the app's **Redirect URLs** ({#configure-oauth}) | -| Issuer URL | Operator-validated constant `https://mcp.intercom.com` | -| Authorization endpoint | Intercom-documented `https://app.intercom.com/oauth` | -| Token endpoint | Intercom-documented `https://api.intercom.io/auth/eagle/token` | Intercom's OAuth guide calls the generated values `client_id` and `client_secret`. It does not say the secret is shown only once, so no one-time @@ -171,7 +163,7 @@ which MCP Server URL the reader adds later. ## Speakeasy setup Canonical source: `doctrine/speakeasy-setup.md`, observed -`2026-07-29T15:06:51Z`. +`2026-08-18T20:24:38Z`. Per-guide values: @@ -184,10 +176,6 @@ Per-guide values: - Client ID and Client Secret: produced in {#copy-client-credentials} - Redirect URI: registered in {#configure-oauth} -- Issuer URL: `https://mcp.intercom.com` -- Authorization endpoint: `https://app.intercom.com/oauth` -- Token endpoint: `https://api.intercom.io/auth/eagle/token` -- Scopes: chosen in Intercom; no Speakeasy scope override - Further reading: `https://developers.intercom.com/docs/guides/mcp` @@ -210,23 +198,15 @@ From the server's **Overview**, open **Settings**. Under **Authentication**, click **Configure Manually**. In **Attach Remote Identity Provider**: 1. Set **Client Type** to **Manual**. -2. Enter `https://mcp.intercom.com` as **Issuer URL**. -3. Under **Endpoints**, set the authorization endpoint to - `https://app.intercom.com/oauth` and the token endpoint to - `https://api.intercom.io/auth/eagle/token`. Do not use the MCP issuer's - discovered `/authorize` and `/token` endpoints for this manual app. -4. Paste the **Client ID** and **Client Secret (optional)** from +2. Paste the **Client ID** and **Client Secret (optional)** from {#copy-client-credentials}. -5. Leave **Scope (override)** and **Audience (optional)** empty because - permissions were selected in Intercom. -6. Confirm that the sheet's **Redirect URI** is - `https://app.getgram.ai/mcp/remote_login_callback`, matching the value - registered through `{{ gram.oauth.callback_url }}` in {#configure-oauth}. -7. Click **Attach Identity Provider**. +3. Confirm that the sheet's **Redirect URI** matches the + `{{ gram.oauth.callback_url }}` value registered in {#configure-oauth}. +4. Click **Attach Identity Provider**. Screenshot note: capture **Attach Remote Identity Provider** with **Client -Type** set to **Manual** and the issuer, authorization, and token endpoint -fields visible. Fully redact the Client ID and Client Secret. +Type** set to **Manual** and the **Redirect URI** visible. Fully redact the +Client ID and Client Secret. When a client first needs Intercom access, complete Intercom's browser authorization prompts with the intended workspace account. Intercom says the @@ -250,9 +230,10 @@ https://developers.intercom.com/docs/guides/mcp." - **OAuth page save control:** Intercom's public OAuth guide names and shows **Use OAuth**, **Redirect URLs**, **Add redirect URL**, and the permission checkboxes, but does not name the control that persists changes. -- **DCR allowlisting process:** operator validation established that DCR needs - callback allowlisting, but Intercom publishes no request path, eligibility - rule, or turnaround time. Manual OAuth remains the recommended path. +- **DCR allowlisting process:** prior operator validation established that DCR + needs callback allowlisting, but Intercom publishes no request path, + eligibility rule, or turnaround time. Manual OAuth remains the recommended + path. ## Provenance @@ -274,39 +255,44 @@ Source inventory from the sweep: Sources drawn from: - `https://developers.intercom.com/docs/guides/mcp` ("Model Context Protocol - (MCP)") — observed `2026-07-29T15:06:51Z`. Backs US/EU URLs and availability, + (MCP)") — observed `2026-08-18T20:24:38Z`. Backs US/EU URLs and availability, Australian exclusion, Streamable HTTP, OAuth and Bearer alternatives, the browser authorization behavior, and the public MCP page's broader **Read and write articles** recommendation. - `https://developers.intercom.com/docs/build-an-integration/getting-started` - and its `.md` representation — observed `2026-07-29T15:06:51Z`. Back the + and its `.md` representation — observed `2026-08-18T20:24:38Z`. Back the Developer Hub URL and **Your Apps**, **New App**, **Create app**, app-name, workspace-selection, and pre-install behavior. - `https://developers.intercom.com/docs/build-an-integration/learn-more/authentication/setting-up-oauth` - and its `.md` representation — observed `2026-07-29T15:06:51Z`. Back **Use + and its `.md` representation — observed `2026-08-18T20:24:38Z`. Back **Use OAuth**, **Authentication**, **Redirect URLs**, HTTPS, **Add redirect URL**, - permissions, **Basic Information**, Client ID/secret, the US authorization - endpoint, callback behavior, and the Eagle token endpoint. + permissions, **Basic Information**, Client ID/secret, the regional US/EU + authorization endpoints, callback behavior, and the Eagle token endpoint. - `https://developers.intercom.com/docs/build-an-integration/learn-more/authentication/oauth-scopes` - — observed `2026-07-29T15:06:51Z`. Backs exact permission labels and their + — observed `2026-08-18T20:24:38Z`. Backs exact permission labels and their access meanings. - `https://developers.intercom.com/docs/build-an-integration/learn-more/authentication` - — observed `2026-07-29T15:06:51Z`. Backs the private Access Token warning and + — observed `2026-08-18T20:24:38Z`. Backs the private Access Token warning and OAuth-versus-token distinction. - `https://developers.intercom.com/llms.txt` — observed - `2026-07-29T15:06:51Z`. Backs developer-property sweep coverage. + `2026-08-18T20:24:38Z`. Backs developer-property sweep coverage. - `https://www.intercom.com/help/en/articles/6124430-regional-data-hosting` - ("Regional Data Hosting") — observed `2026-07-29T15:06:51Z`. Backs the + ("Regional Data Hosting") — observed `2026-08-18T20:24:38Z`. Backs the workspace-host mapping and wrong-region sign-in recovery. - `https://app.intercom.com/admins/sign_in` — observed - `2026-07-29T15:06:51Z`. Backs the current region-selector labels. + `2026-08-18T20:24:38Z`. Backs the current region-selector labels. - `https://mcp.intercom.com/.well-known/oauth-authorization-server` — - observed `2026-07-29T15:06:51Z`. Confirms that the MCP issuer advertises DCR - and separate `/authorize` and `/token` endpoints. -- Operator validation recorded for this run — observed - `2026-07-29T15:06:51Z`. Backs DCR callback-allowlist failure, the recommended - manual OAuth path, callback URL, validated issuer/authorization/token values, - and the least-privilege permission set. -- `doctrine/speakeasy-setup.md` — observed `2026-07-29T15:06:51Z`. Backs the + observed `2026-08-18T20:24:38Z`. Prior observation established that the MCP + issuer advertises DCR and separate `/authorize` and `/token` endpoints; an + unauthenticated automated refresh this run returned HTTP 403, so that prior + result is retained rather than replaced. +- Prior operator validation retained in the Guide and reviewed this run — + observed `2026-08-18T20:24:38Z`. Backs DCR callback-allowlist failure, the + recommended manual OAuth path, callback URL, the validated US + issuer/authorization/token values, and the least-privilege permission set. + The current OAuth guide's regional endpoint table was rechecked this run; it + explicitly confirms the EU authorization endpoint as + `https://app.eu.intercom.com/oauth`. +- `doctrine/speakeasy-setup.md` — observed `2026-08-18T20:24:38Z`. Backs the canonical Speakeasy skeleton, fixed anchors, exact common labels, and tenanted Custom-remote path selection. diff --git a/guides/intercom/speakeasy.md b/guides/intercom/speakeasy.md index f9dea6b..b006b98 100644 --- a/guides/intercom/speakeasy.md +++ b/guides/intercom/speakeasy.md @@ -17,22 +17,12 @@ This creates the hosted MCP server and opens its **Overview** page. 1. From the server's **Overview**, open **Settings**. 2. Under **Authentication**, click **Configure Manually**. 3. In **Attach Remote Identity Provider**, set **Client Type** to **Manual**. -4. Enter `https://mcp.intercom.com` as **Issuer URL**. -5. Under **Endpoints**, set the authorization endpoint to `https://app.intercom.com/oauth`. -6. Set the token endpoint to this URL: - - ``` - https://api.intercom.io/auth/eagle/token - ``` - -7. Paste the **Client ID** from [Copy the client credentials](external.md#copy-client-credentials). -8. Paste the **Client Secret (optional)** from [Copy the client credentials](external.md#copy-client-credentials). -9. Leave **Scope (override)** empty. -10. Leave **Audience (optional)** empty. -11. Confirm that **Redirect URI** is `{{ gram.oauth.callback_url }}`, matching the value registered in [Configure OAuth](external.md#configure-oauth). -12. Click **Attach Identity Provider**. - - +4. Paste the **Client ID** from [Copy the client credentials](external.md#copy-client-credentials). +5. Paste the **Client Secret (optional)** from [Copy the client credentials](external.md#copy-client-credentials). +6. Confirm that the sheet's **Redirect URI** matches the `{{ gram.oauth.callback_url }}` value registered in [Configure OAuth](external.md#configure-oauth). +7. Click **Attach Identity Provider**. + + When a client initiates Intercom access, complete the on-screen browser prompts with the intended workspace account. diff --git a/retro/runs/2026-08-18T20:24:38Z-intercom.json b/retro/runs/2026-08-18T20:24:38Z-intercom.json new file mode 100644 index 0000000..2215bc5 --- /dev/null +++ b/retro/runs/2026-08-18T20:24:38Z-intercom.json @@ -0,0 +1,61 @@ +{ + "slug": "intercom", + "provider": "intercom", + "persona": "it-admin", + "timestamp": "2026-08-18T20:24:38Z", + "started_at": "2026-08-18T20:24:38Z", + "finished_at": "2026-08-18T20:29:22Z", + "runtime": "pi", + "status": "converged", + "rounds": 2, + "nits": [], + "open_questions": [ + "Intercom's public app-creation documentation does not publish the exact app-name and workspace field labels.", + "Intercom does not publish the current authorization-screen sequence or approval-button labels.", + "Intercom's public OAuth guide does not name the control that persists Authentication-page changes.", + "Intercom does not document the issuer value for an EU manually attached client; the matching EU MCP origin is a flagged inference.", + "Intercom does not publish a DCR callback-allowlisting request path, eligibility rule, or turnaround time." + ], + "history": [ + { + "round": 1, + "blockers": [ + { + "severity": "blocker", + "target": "research", + "where": "Speakeasy setup > Connect your credentials", + "problem": "The manual OAuth flow adds Issuer URL, endpoint override, Scope override, and Audience steps that are absent from the canonical pre-registered-client variant in doctrine/speakeasy-setup.md.", + "suggestion": "Align the Dossier and speakeasy.md with the canonical manual OAuth variant, or have a human update the canonical doctrine to support the operator-validated manual endpoint override before rendering these additional steps.", + "dimension": "fidelity" + }, + { + "severity": "blocker", + "target": "meta", + "where": "remotes[id=eu].provenance[source=operator-validation]", + "problem": "The EU remote claims manual OAuth was validated, while the Research Dossier says operator validation covered only the US flow and treats the EU issuer as an inference.", + "suggestion": "Remove the EU manual-validation claim or change its status to accurately distinguish the provider-documented EU endpoint from the inferred, unvalidated EU issuer.", + "dimension": "fidelity" + } + ], + "nits": [], + "revision_notes": "Research fidelity: aligned the Research Dossier and speakeasy.md with the canonical pre-registered OAuth variant by removing Issuer URL, endpoint override, Scope override, and Audience steps while retaining Client ID, Client Secret, Redirect URI confirmation, and attachment. Metadata fidelity: removed the EU remote's operator-validation claim; the US remote retains its validated status, matching the Dossier.", + "disputed": [], + "skipped": [] + }, + { + "round": 2, + "blockers": [], + "nits": [] + } + ], + "research_change": { + "method": "judge", + "unchanged": false, + "notes": "AFTER adds region-specific OAuth attachment values for EU workspaces: the documented authorization endpoint is now https://app.eu.intercom.com/oauth instead of the previously universal US endpoint, and the Guide now uses https://mcp.eu.intercom.com as the EU issuer (explicitly flagged as an inference, with only the US manual flow operator-validated). These changes require re-rendering speakeasy.md and invalidate prior review of the EU setup path. Remotes, transport, credentials, prerequisites, anchors, permissions, and the Custom-remote-only path are otherwise unchanged." + }, + "notes_digest": "sha256:c7cf376207c389683202db431abf3f8ccace4607ffe4357ab0d94ed389db1652", + "setup_churn": { + "external_md_lines": 0, + "speakeasy_md_lines": 17 + } +}