diff --git a/guides/intercom/external.md b/guides/intercom/external.md index 4c6b792..41a4b19 100644 --- a/guides/intercom/external.md +++ b/guides/intercom/external.md @@ -29,9 +29,10 @@ If Intercom cannot find the workspace: 1. Open the [Intercom Developer Hub](https://app.intercom.com/a/apps/_/developer-hub). This opens **Your Apps**. 2. Select **New App**. -3. In the modal, enter an organization-approved app name. -4. Select the workspace this connection will access. -5. Select **Create app**. +3. Obtain the organization-approved app name from the application or cloud security owner. +4. In the modal, enter that app name. +5. Select the workspace this connection will access. +6. Select **Create app**. Intercom creates the app, installs it in the selected workspace, and opens its configuration. @@ -53,7 +54,7 @@ Intercom creates the app, installs it in the selected workspace, and opens its c - **Read conversations** - **Read one admin** - **Read and List articles** -6. If the organization requires article creation or updates through the MCP server, select **Read and Write Articles** instead of **Read and List articles**. +6. Obtain the article-access choice from the application or cloud security owner. Unless they require article creation or updates through the MCP server, keep **Read and List articles**. If they require those operations, select **Read and Write Articles** instead. 7. Complete the page's save or confirmation control. diff --git a/guides/intercom/meta.yaml b/guides/intercom/meta.yaml index 901c5ea..f20c6d6 100644 --- a/guides/intercom/meta.yaml +++ b/guides/intercom/meta.yaml @@ -40,7 +40,7 @@ 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-11T18:35:57Z" - source: operator-validation locator: draft-guide operator notes for intercom status: manual OAuth validated @@ -56,7 +56,7 @@ 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-11T18:35:57Z" - source: operator-validation locator: draft-guide operator notes for intercom status: manual OAuth validated @@ -66,46 +66,50 @@ provenance: 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-11T18:35:57Z" - 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-11T18:35:57Z" - 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-11T18:35:57Z" - 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-11T18:35:57Z" - 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-11T18:35:57Z" - 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-11T18:35:57Z" - 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-11T18:35:57Z" - 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-11T18:35:57Z" - 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-11T18:35:57Z" + - source: endpoint-observation + locator: https://mcp.eu.intercom.com/.well-known/oauth-authorization-server + classification: official + observed_at: "2026-08-11T18:35:57Z" - source: operator-validation locator: draft-guide operator notes for intercom status: manual OAuth recommended; DCR requires callback allowlisting @@ -114,4 +118,4 @@ provenance: locator: doctrine/speakeasy-setup.md name: Speakeasy setup canonical section classification: official - observed_at: "2026-07-29T15:06:51Z" + observed_at: "2026-08-11T18:35:57Z" diff --git a/guides/intercom/pipeline.lock.json b/guides/intercom/pipeline.lock.json index a5444e4..f2fed9c 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-11T18:44:19Z", "steps": { "research": { - "input_digest": "sha256:6e304ac36ef5fa89975820896e4504a53a2f7f0f33a7467084c29cfe7c2ec33d", + "input_digest": "sha256:487b2071c2ca0c4aa5a85bfbf6704583b4c4c4c0af39550d5d6f4921ee792042", "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 due to lockfile drift; rerun research, draft, fidelity review, and achievability review under the pi runtime.\n\nSpeakeasy MCP Catalog: overridden-tenanted" } }, "outputs": [ { "path": "research.md", - "digest": "sha256:c3bfaadb51be5575c5821a2f08e04b9eeb67394a1c35227485a45191ea3bfd91" + "digest": "sha256:970009f3cafa137334aed43d66cea12e84c08bf96c0b01de25b6f26d96e0c921" }, { "path": "meta.yaml", - "digest": "sha256:071b0fee3b30edcf251da79d7d4b104c51141ed9967170e4e26ec73952b953f2" + "digest": "sha256:49c7ae2575461ab2d9e89c996be39c55b2118a413867b4de114cd0daa928d710" } ], - "completed_at": "2026-07-29T15:15:59Z" + "completed_at": "2026-08-11T18:44:19Z" }, "draft": { - "input_digest": "sha256:04c63eed17b390d2d47b469dee79b55092b6be3a19f5e5fa93a42fa7e597cd23", + "input_digest": "sha256:669dfbeead749fc4d85688adc2dbd954a10f0972181ddcff705ca434ee159578", "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:970009f3cafa137334aed43d66cea12e84c08bf96c0b01de25b6f26d96e0c921" }, { "path": "meta.yaml", - "digest": "sha256:071b0fee3b30edcf251da79d7d4b104c51141ed9967170e4e26ec73952b953f2" + "digest": "sha256:49c7ae2575461ab2d9e89c996be39c55b2118a413867b4de114cd0daa928d710" } ], "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 due to lockfile drift; rerun research, draft, fidelity review, and achievability review under the pi runtime.\n\nSpeakeasy MCP Catalog: overridden-tenanted", "persona": "it-admin" } }, "outputs": [ { "path": "external.md", - "digest": "sha256:2b8ea05a45dbf45d45573755807ab19d9d23de0a4447798d84bc18673a80ae0f" + "digest": "sha256:605697dd0cff35582a05723308f56347fbe5276f83ef7cf84e096e41d9a7074d" }, { "path": "speakeasy.md", - "digest": "sha256:062bfa48925435cff15b96a7e1a2c9c207b215e0d74675696e7f1d8cdc679889" + "digest": "sha256:28c22052fb3b45e978b47c0c5d2414841034c8dfb635b25d6aadef638d150919" } ], - "completed_at": "2026-07-29T15:15:59Z" + "completed_at": "2026-08-11T18:44:19Z" }, "review.fidelity": { - "input_digest": "sha256:3c91cc5b556b2b46bdb54294e6d305e843ec4820595f2ba92970e362fc202f06", + "input_digest": "sha256:5153024ad2d2af45119277f9805a3d5c7a807972d41fd6e445bdcb7a88695511", "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:970009f3cafa137334aed43d66cea12e84c08bf96c0b01de25b6f26d96e0c921" }, { "path": "meta.yaml", - "digest": "sha256:071b0fee3b30edcf251da79d7d4b104c51141ed9967170e4e26ec73952b953f2" + "digest": "sha256:49c7ae2575461ab2d9e89c996be39c55b2118a413867b4de114cd0daa928d710" }, { "path": "external.md", - "digest": "sha256:2b8ea05a45dbf45d45573755807ab19d9d23de0a4447798d84bc18673a80ae0f" + "digest": "sha256:605697dd0cff35582a05723308f56347fbe5276f83ef7cf84e096e41d9a7074d" }, { "path": "speakeasy.md", - "digest": "sha256:062bfa48925435cff15b96a7e1a2c9c207b215e0d74675696e7f1d8cdc679889" + "digest": "sha256:28c22052fb3b45e978b47c0c5d2414841034c8dfb635b25d6aadef638d150919" } ], "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 due to lockfile drift; rerun research, draft, fidelity review, and achievability review under the pi runtime.\n\nSpeakeasy MCP Catalog: overridden-tenanted", "persona": "it-admin", "dimension": "fidelity" } @@ -144,20 +144,20 @@ "outputs": [ { "path": "external.md", - "digest": "sha256:2b8ea05a45dbf45d45573755807ab19d9d23de0a4447798d84bc18673a80ae0f" + "digest": "sha256:605697dd0cff35582a05723308f56347fbe5276f83ef7cf84e096e41d9a7074d" }, { "path": "speakeasy.md", - "digest": "sha256:062bfa48925435cff15b96a7e1a2c9c207b215e0d74675696e7f1d8cdc679889" + "digest": "sha256:28c22052fb3b45e978b47c0c5d2414841034c8dfb635b25d6aadef638d150919" } ], - "completed_at": "2026-07-29T15:15:59Z" + "completed_at": "2026-08-11T18:44:19Z" }, "review.achievability": { - "input_digest": "sha256:85247bea46b2cccffcd67c772613725fc8fe103e478be89341a990d1c08f4335", + "input_digest": "sha256:e10fb9984ea4c2c20a62154cee2e63387d36bf6484a3e8fc557d37e8d9bb1884", "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:970009f3cafa137334aed43d66cea12e84c08bf96c0b01de25b6f26d96e0c921" }, { "path": "meta.yaml", - "digest": "sha256:071b0fee3b30edcf251da79d7d4b104c51141ed9967170e4e26ec73952b953f2" + "digest": "sha256:49c7ae2575461ab2d9e89c996be39c55b2118a413867b4de114cd0daa928d710" }, { "path": "external.md", - "digest": "sha256:2b8ea05a45dbf45d45573755807ab19d9d23de0a4447798d84bc18673a80ae0f" + "digest": "sha256:605697dd0cff35582a05723308f56347fbe5276f83ef7cf84e096e41d9a7074d" }, { "path": "speakeasy.md", - "digest": "sha256:062bfa48925435cff15b96a7e1a2c9c207b215e0d74675696e7f1d8cdc679889" + "digest": "sha256:28c22052fb3b45e978b47c0c5d2414841034c8dfb635b25d6aadef638d150919" } ], "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 due to lockfile drift; rerun research, draft, fidelity review, and achievability review under the pi runtime.\n\nSpeakeasy MCP Catalog: overridden-tenanted", "persona": "it-admin", "dimension": "achievability" } @@ -204,14 +204,14 @@ "outputs": [ { "path": "external.md", - "digest": "sha256:2b8ea05a45dbf45d45573755807ab19d9d23de0a4447798d84bc18673a80ae0f" + "digest": "sha256:605697dd0cff35582a05723308f56347fbe5276f83ef7cf84e096e41d9a7074d" }, { "path": "speakeasy.md", - "digest": "sha256:062bfa48925435cff15b96a7e1a2c9c207b215e0d74675696e7f1d8cdc679889" + "digest": "sha256:28c22052fb3b45e978b47c0c5d2414841034c8dfb635b25d6aadef638d150919" } ], - "completed_at": "2026-07-29T15:15:59Z" + "completed_at": "2026-08-11T18:44:19Z" } } } diff --git a/guides/intercom/research.md b/guides/intercom/research.md index 8b2296f..f12c100 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-11T18:35:57Z --- # Intercom — Research Dossier @@ -10,11 +10,12 @@ Source ruling for this revision: Intercom's public MCP guide remains authoritative for regional server URLs, transport, and server availability. Intercom's current Developer Hub guides are authoritative for creating an app, enabling OAuth, exact permission labels, callback requirements, and the -authorization and token endpoints. The operator's current connection -validation overrides the prior DCR recommendation: DCR fails when Intercom has -not allowlisted the Speakeasy callback, so this Guide documents a manually -registered Intercom OAuth app as the recommended, deterministic path. The -operator's Speakeasy MCP Catalog result is `overridden-tenanted`; because the +authorization and token endpoints. Prior operator connection validation overrides the earlier DCR recommendation: +DCR fails when Intercom has not allowlisted the Speakeasy callback, so this +Guide documents a manually registered Intercom OAuth app as the recommended, +deterministic path. Fresh public-documentation and endpoint checks during this +run found no change to that ruling. The operator's Speakeasy MCP Catalog result +is `overridden-tenanted`; because the reader chooses a region-specific remote URL, only the Custom remote server path is rendered. @@ -33,12 +34,17 @@ is rendered. - **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` + - Issuer URL: the origin of the selected remote, + `https://mcp.intercom.com` (US) or `https://mcp.eu.intercom.com` (EU) + - Authorization endpoint: `https://app.intercom.com/oauth` (US) or + `https://app.eu.intercom.com/oauth` (EU) - 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. + The manual attachment flow was validated previously by the operator. Fresh + checks confirm that each regional MCP origin publishes authorization-server + metadata with that origin as its issuer, while Intercom's OAuth guide says to + match the authorization host to the workspace region and documents the + shared Eagle token endpoint. Using the wrong authorization region can fail + for Google sign-in; otherwise Intercom may ask the user to select a region. - **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,8 +96,8 @@ 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` | +| Issuer URL | Selected MCP remote origin: `https://mcp.intercom.com` (US) or `https://mcp.eu.intercom.com` (EU) | +| Authorization endpoint | Region-matched Intercom endpoint: `https://app.intercom.com/oauth` (US) or `https://app.eu.intercom.com/oauth` (EU) | | Token endpoint | Intercom-documented `https://api.intercom.io/auth/eagle/token` | Intercom's OAuth guide calls the generated values `client_id` and @@ -128,8 +134,10 @@ which MCP Server URL the reader adds later. - Click **New App**. Intercom's prose uses **New App**; its current documentation screenshot describes the highlighted control as **Create new app**. -- In the modal, enter an organization-approved app name and select the - workspace the connection will access. +- Obtain the organization-approved app name from the application or cloud + security owner. +- In the modal, enter that app name and select the workspace the connection + will access. - Click **Create app**. Intercom creates the app, pre-installs it in the selected workspace, and opens the app configuration. - Screenshot note: capture **Your Apps** with the new-app control and the @@ -150,8 +158,10 @@ which MCP Server URL the reader adds later. - **Read conversations** - **Read one admin** - **Read and List articles** -- If article creation or update through the MCP server is explicitly required, - select **Read and Write Articles** instead of **Read and List articles**. +- Obtain the article-access choice from the application or cloud security owner. + Unless they require article creation or updates through the MCP server, keep + **Read and List articles**. If they require those operations, select **Read + and Write Articles** instead. - Complete the page's save or confirmation control. Intercom's public guide names and shows the fields but does not name that control. - Screenshot note: capture **Authentication** with **Use OAuth** enabled, @@ -171,7 +181,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-11T18:35:57Z`. Per-guide values: @@ -184,9 +194,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` @@ -207,26 +214,18 @@ MCP server** page with the matching Intercom remote URL. ### Connect your credentials {#connect-speakeasy-credentials} From the server's **Overview**, open **Settings**. Under **Authentication**, -click **Configure Manually**. In **Attach Remote Identity Provider**: +click **Configure Manually**. In the **Attach Remote Identity Provider** sheet: 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. Click **Attach Identity Provider**. +4. Confirm that the sheet's **Redirect URI** matches the + `{{ gram.oauth.callback_url }}` value registered in {#configure-oauth}. 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 **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 @@ -270,43 +269,51 @@ Source inventory from the sweep: not used because its README was stale relative to the live MCP guide. - **Speakeasy setup doctrine — `doctrine/speakeasy-setup.md`:** canonical Speakeasy-side flow and fixed anchors. +- **Persona doctrine — `doctrine/personas/it-admin.md`:** canonical source for + the obtain-from-owner hedge on organization-specific values. 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-11T18:35:57Z`. 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-11T18:35:57Z`. 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-11T18:35:57Z`. 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 + authorization endpoints, callback behavior, wrong-region 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-11T18:35:57Z`. 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-11T18:35:57Z`. 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-11T18:35:57Z`. 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-11T18:35:57Z`. 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. -- `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 + `2026-08-11T18:35:57Z`. Backs the current region-selector labels. +- `https://mcp.intercom.com/.well-known/oauth-authorization-server` and + `https://mcp.eu.intercom.com/.well-known/oauth-authorization-server` — + observed `2026-08-11T18:35:57Z`. Confirm each regional MCP issuer, DCR + registration endpoint, and separate `/authorize` and `/token` endpoints. +- Prior operator validation retained from the existing Guide — originally + observed `2026-07-29T15:06:51Z`. Backs DCR callback-allowlist failure, the + recommended manual OAuth path, callback URL, validated manual attachment, + and the least-privilege permission set. This run did not repeat a credentialed + connection. +- `doctrine/speakeasy-setup.md` — observed `2026-08-11T18:35:57Z`. Backs the canonical Speakeasy skeleton, fixed anchors, exact common labels, and tenanted Custom-remote path selection. +- `doctrine/personas/it-admin.md` — observed `2026-08-11T18:35:57Z`. Backs + directing the reader to obtain an organization-specific app name from the + application or cloud security owner. diff --git a/guides/intercom/speakeasy.md b/guides/intercom/speakeasy.md index f9dea6b..afdd8ea 100644 --- a/guides/intercom/speakeasy.md +++ b/guides/intercom/speakeasy.md @@ -16,23 +16,13 @@ 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**. - - +3. In the **Attach Remote Identity Provider** sheet, set **Client Type** to **Manual**. +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. Click **Attach Identity Provider**. +7. Confirm that the sheet's **Redirect URI** matches the `{{ gram.oauth.callback_url }}` value registered in [Configure OAuth](external.md#configure-oauth). + + When a client initiates Intercom access, complete the on-screen browser prompts with the intended workspace account. diff --git a/retro/runs/2026-08-11T18:35:57Z-intercom.json b/retro/runs/2026-08-11T18:35:57Z-intercom.json new file mode 100644 index 0000000..b9fb473 --- /dev/null +++ b/retro/runs/2026-08-11T18:35:57Z-intercom.json @@ -0,0 +1,87 @@ +{ + "slug": "intercom", + "provider": "intercom", + "persona": "it-admin", + "timestamp": "2026-08-11T18:35:57Z", + "started_at": "2026-08-11T18:35:57Z", + "finished_at": "2026-08-11T18:44:20Z", + "runtime": "pi", + "status": "converged", + "rounds": 3, + "nits": [], + "open_questions": [ + "Intercom’s public app-creation documentation does not publish the exact labels for the app-name and workspace fields.", + "Intercom documents authorization behavior but not the current prompt sequence or approval-button labels.", + "Intercom’s public OAuth guide does not name the control that persists Authentication-page changes.", + "Intercom does not publish the DCR callback-allowlisting request path, eligibility rules, or turnaround time." + ], + "history": [ + { + "round": 1, + "blockers": [ + { + "severity": "blocker", + "target": "research", + "where": "Connect your credentials {#connect-speakeasy-credentials}", + "problem": "The pre-registered OAuth transclusion adds manual Issuer URL and authorization/token endpoint steps that are absent from the current canonical Speakeasy skeleton.", + "suggestion": "Restore the canonical pre-registered OAuth skeleton without the added issuer and endpoint inputs; if Intercom cannot connect without those inputs, escalate the conflict for a human doctrine update rather than presenting the section as a canonical transclusion.", + "dimension": "fidelity" + } + ], + "nits": [ + { + "severity": "nit", + "target": "external", + "where": "#configure-oauth, step 6", + "problem": "The guide leaves the reader to determine whether the organization requires article creation or updates without naming whom to ask.", + "suggestion": "Tell the reader to obtain the article-access choice from the application or cloud security owner and otherwise keep the read-only article permission.", + "dimension": "achievability" + } + ], + "revision_notes": "Blocker (research/Speakeasy fidelity): restored the canonical pre-registered OAuth credential flow in research.md and speakeasy.md by removing manual Issuer URL, authorization endpoint, token endpoint, scope, and audience inputs; retained the fixed anchors and Custom remote-only add-server path. Nit (external/achievability): updated Configure OAuth step 6 in research.md and external.md to direct the reader to obtain the article-access choice from the application or cloud security owner and otherwise keep the read-only article permission.", + "disputed": [], + "skipped": [] + }, + { + "round": 2, + "blockers": [ + { + "severity": "blocker", + "target": "research", + "where": "Connect your credentials {#connect-speakeasy-credentials}", + "problem": "The pre-registered OAuth transclusion moves Redirect URI confirmation before credential entry and attachment, while the current canonical Speakeasy skeleton places confirmation after clicking Attach Identity Provider.", + "suggestion": "Restore the canonical action order in research.md, then render the same order in speakeasy.md: enter the credentials, click Attach Identity Provider, and confirm the Redirect URI as specified by doctrine/speakeasy-setup.md.", + "dimension": "fidelity" + } + ], + "nits": [ + { + "severity": "nit", + "target": "external", + "where": "#create-oauth-app, step 3", + "problem": "The reader is told to enter an organization-approved app name but is not told whom to ask for that required organization-specific value.", + "suggestion": "Direct the reader to obtain the app name from the application or cloud security owner.", + "dimension": "achievability" + } + ], + "revision_notes": "Blocker: restored the canonical pre-registered OAuth order in research.md and speakeasy.md: enter Client ID and Client Secret, click Attach Identity Provider, then confirm Redirect URI. Nit: updated research.md and external.md so the reader obtains the organization-approved app name from the application or cloud security owner; recorded persona-doctrine provenance with the supplied observed_at timestamp.", + "disputed": [], + "skipped": [] + }, + { + "round": 3, + "blockers": [], + "nits": [] + } + ], + "research_change": { + "method": "judge", + "unchanged": false, + "notes": "AFTER adds draft-relevant EU OAuth configuration: EU workspaces must use issuer https://mcp.eu.intercom.com and authorization endpoint https://app.eu.intercom.com/oauth instead of the prior US-only values. It also documents wrong-region authorization behavior and adds provenance from the EU authorization-server metadata. This requires re-rendering the Speakeasy credential steps and invalidates prior review of the EU setup path." + }, + "notes_digest": "sha256:ffc943311a21d826614a53709fcfdd912146ca217296218253c307dfc3eeca17", + "setup_churn": { + "external_md_lines": 0, + "speakeasy_md_lines": 0 + } +}