service-discoverability
Service Discoverability
What This Is
When an AI agent is handed only your app's URL (e.g. https://yourapp.com), it should be able to work out the rest on its own: which canisters the 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.
This skill covers what a canister app publishes to make that possible, across five layers. Layer 1 is gated: it is what an app publishes to participate in ICP MCP, and publishing it accepts an agreement on the operator's behalf — read Before Layer 1 before writing that file. Layers 2-5 are ungated and independently adoptable; each is useful on its own, and together they make an app agent-ready.
| Layer | Question it answers | Mechanism |
|---|---|---|
| 1. Composition | Which canisters make up this app, and what is each for? | /.well-known/ic-architecture JSON manifest |
| 2. Interface | What methods and types does a canister expose? | candid:service metadata |
| 3. Behavior | How does it actually behave (units, lifecycle, gotchas)? | getApiDoc query method |
| 4. Data | How do I query its data without a method per question? | OQL schema + execute query methods |
| 5. Identity | How do I act as the signed-in user, under the right principal? | /.well-known/ii-derivation-origin file |
The load-bearing move for Layers 1 and 5 is generating the well-known files at deploy time, because the canister IDs (and the mainnet origin) differ per network. This skill uses the @dfinity/static-site recipe's presync hook to do that — the same pattern demonstrated by the community example raymondk/demo-ic-architecture.