Skip to content

Commit f8a1d96

Browse files
atergaclaude
andauthored
docs: state that adopting service discoverability opts an app in to ICP MCP (#372)
## Summary Adds a visible disclaimer to `docs/guides/frontends/service-discoverability.md` stating that adopting the protocol opts an app in to being discovered by ICP MCP, under its terms of service and privacy policy. The protocol's whole purpose is that an agent handed only an app's URL can work the rest out unattended, so publishing the manifest is the moment the app becomes usable by agents that read it. The page did not say so. It does now, above the fold, before any of the instructions it qualifies. Wording: > **Adopting this protocol opts your app in** > > By implementing this service discoverability protocol for your app, you agree that your app should be discovered by [ICP MCP](https://internetcomputer.org/icp-mcp/), that you accept its [terms of service](https://internetcomputer.org/icp-mcp/terms/), and that you comply with its [privacy policy](https://internetcomputer.org/icp-mcp/privacy-policy/). Publishing the Layer 1 manifest at `/.well-known/ic-architecture` is the act that opts your app in: the layers are otherwise independently adoptable, and the rest of them describe how an agent works with an app once it has been discovered. Two smaller changes came out of review: the page `description` now names ICP MCP, and the opening line speaks of "an agent working through ICP MCP" rather than an abstract AI agent. ## Structural decisions - **Placement:** immediately after the intro paragraph and before `## The five layers`, so it is read before the instructions it qualifies rather than being buried under them. - **Aside type:** `:::caution` (used 11 times elsewhere in `docs/`) rather than `:::note`, since the point was that it be clearly visible, and it carries an agreement rather than an aside. - **Naming the trigger:** without the second sentence, "implementing this service discoverability protocol" sat in tension with the page's own "each layer is independently adoptable", leaving it unclear whether exposing only `getApiDoc` or an `ii-derivation-origin` also opts an app in. It does not, and naming the manifest makes the page agree with what the connector actually keys on ([dfinity/imcp2#166](dfinity/imcp2#166) gates writes on exactly that document). - **Why the consent statement is not in the frontmatter `description`:** Starlight puts that field only into the page's `description` and `og:description` meta tags, which cannot render markdown, so links there would show as literal brackets in search results and link previews. The statement lives in the aside, where it renders and where a reader sees it. - **Links:** all three target `internetcomputer.org/icp-mcp/`, verified live (HTTP 200; the pages render "ICP MCP Terms of Service" and "ICP MCP Privacy Policy"). ## Verified - `npm run build` passes on every commit; the page renders the aside as `starlight-aside--caution` with all links intact, confirmed on the deployed preview. - No em-dashes, no `dfx`, no banned vocabulary (checked against `icp-brand-voice`). - The two remaining "AI agents" in the built page come from the site-wide `agent-signaling` blockquote and llms.txt footer, injected into every page by the `agent-docs` integration; out of scope here. - `package-lock.json`, touched by `npm install` during setup, is deliberately not included. ## Note for reviewers @sea-snake approved at `b7e5e2b`. Two further commits landed after that, both addressing review comments on this PR (`d9fe5df`, `389828e`), so the approving commit is no longer the head and the approval may need refreshing. --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 6841705 commit f8a1d96

1 file changed

Lines changed: 6 additions & 2 deletions

File tree

‎docs/guides/frontends/service-discoverability.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,18 @@
11
---
22
title: "Service discoverability"
3-
description: "What a canister app exposes so an AI agent can discover its canisters, interfaces, behavior, data, and identity from just its URL"
3+
description: "What an app exposes so ICP MCP can discover its canisters, interfaces, behavior, data, and identity from just its URL."
44
sidebar:
55
order: 3
66
---
77

8-
When an AI agent is handed only your app's URL (for example, `https://yourapp.com`), it should be able to work out the rest on its own: which canisters your app comprises, what each one does, how to call them, how to query their data, and how to act as the signed-in user. No human supplying canister IDs, no bespoke integration.
8+
When an agent working through ICP MCP is handed only your app's URL (for example, `https://yourapp.com`), it should be able to work out the rest on its own: which canisters your app comprises, what each one does, how to call them, how to query their data, and how to act as the signed-in user. No human supplying canister IDs, no bespoke integration.
99

1010
This guide describes what a canister app exposes to make that possible, ordered by priority.
1111

12+
:::caution[Adopting this protocol opts your app in]
13+
By implementing this service discoverability protocol for your app, you agree that your app should be discovered by [ICP MCP](https://internetcomputer.org/icp-mcp/), that you accept its [terms of service](https://internetcomputer.org/icp-mcp/terms/), and that you comply with its [privacy policy](https://internetcomputer.org/icp-mcp/privacy-policy/). Publishing the Layer 1 manifest at `/.well-known/ic-architecture` is the act that opts your app in: the layers are otherwise independently adoptable, and the rest of them describe how an agent works with an app once it has been discovered.
14+
:::
15+
1216
## The five layers
1317

1418
An agent handed only your app's URL should be able to do five things, unattended:

0 commit comments

Comments
 (0)