docs: clarify manifest opt-in and optional registration

[aterga]

Summary

Follow-up to #376. That PR correctly retargeted the opt-in caution from the old single terms of service to the App Operator Terms, but it inherited the ambiguity those Terms carried: it presented registration as the acceptance step while also treating manifest publication as acceptance by conduct, so a reader could not tell what they must do before their app can be acted on.

dfinity/internetcomputer-org#96 resolved that in the Terms themselves. This states the same model here, which matters because the Terms point at this page for how acceptance happens (and say that where the two differ, the Terms prevail).

What the caution now says

• Publishing the Layer 1 manifest at /.well-known/ic-architecture opts the app in and constitutes the operator's acceptance of the App Operator Terms. It is sufficient to make the app's declared canisters eligible for everything ICP MCP does with them, queries and state-changing calls alike; no separate registration is required.
• Publication is the condition ICP MCP applies to every call that reaches a canister. It reads and calls only canisters a manifest declares, so an app that publishes none is still resolved and described, but none of its canisters is read or called. Removing the manifest stops new calls of every kind.
• Registration is optional and is not a condition of participation. It is how an operator tells DFINITY who they are, so they can be reached with the notices the terms provide for, and so there is a record of who accepted and which version; it can carry the URL of the app's own privacy policy so ICP MCP can present it to users.
• The privacy sentence describes what the ICP MCP Privacy Policy actually covers (what is disclosed to a participating app, and what registration processes), and states that the operator remains responsible for handling that data lawfully and for keeping the app's own privacy notice accurate — rather than asking operators to "comply with" a notice that describes DFINITY's processing and expressly does not govern theirs.
• The caution title now names the trigger ("Publishing the Layer 1 manifest opts your app in"), which review caught contradicting the body: the old title read as though any layer opts an app in, while the body pins opt-in to Layer 1 and notes the layers are otherwise independently adoptable.

The five-layer content below the caution is unchanged.

Revision history

This PR went through three models of what publication gates, because the code moved under it:

1. An early revision gated state-changing calls on DFINITY confirming the operator's registration. That was the wrong branch of the two the review offered; publication really was sufficient, so registration became optional instead.
2. Two review suggestions then narrowed what publication gates to state-changing calls only, on the correct ground that crates/imcp2-core/src/discoverability.rs gated writes only and its READS_ARE_FINE refusal text told agents that reads worked regardless. Both were applied verbatim in 60a73a0 and 8ec933f.
3. e4ce4be undoes that narrowing, because Gate every canister-reaching tool on the discoverability manifest imcp2#184 (64c48be, "Gate every canister-reaching tool on the discoverability manifest") has since made reads gated the same way. get_canister_candid, get_canister_api_doc, get_canister_oql_schema, canister_query on both paths and canister_update_call are all restricted to declared canisters; per the module docs, "Reads and writes share one mechanism and differ only in what a refusal SAYS", the_rule() now says the server "reads and calls ONLY canisters an app declares", and READS_ARE_FINE is gone.

So the two suggested sentences were accurate when written and are not now. Step 3 keeps their substance where it still holds (publication is sufficient, registration is optional) and moves the line to where the code now draws it: not reads versus writes, but calls that reach a canister versus the surface that does not. open_app, the static guides and the identity tools reach no canister and stay ungated, which is why the caution still says an app publishing no manifest is resolved and described.

@sea-snake, your approval was on 8ec933f, so this last commit is newer than what you read.

Verification

• npm run validate — 210 files, all checks passed on each revision, including e4ce4be (the repo's no-em-dash rule caught new prose in the first draft, fixed before pushing).
• Rendered preview checked, not just the source, on the earlier revisions: the caution reads as intended and the page links only app-operator-terms/ and privacy-policy/, with no /icp-mcp/terms/ link that would send operators to the User Terms.
• The claims about the gate are quoted from crates/imcp2-core/src/discoverability.rs at imcp2 main (64c48be), not from memory.

Companion

dfinity/internetcomputer-org#97 makes the matching correction to App Operator Terms §3, §4 and §7. Merge that with or before this, since the Terms are the authority this page defers to.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Xpg83AWtkQo34jbMxpX8WB

[Copilot]

🟡 Changes recommended

The caution title contradicts the newly clarified Layer 1-specific opt-in trigger.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Clarifies ICP MCP’s two-tier opt-in model and app operator privacy responsibilities.

Changes:

• Defines Layer 1 publication as acceptance.
• Separates read-only access from registered state-changing calls.
• Clarifies privacy-policy responsibilities.

File summaries

File	Description
docs/guides/frontends/service-discoverability.md	Updates the opt-in caution and registration guidance.

Review details

• Files reviewed: 1/1 changed files
• Comments generated: 1
• Review effort level: Balanced

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[aterga]

e4ce4be reverses the narrowing that the two review suggestions introduced, because the code moved.

dfinity/imcp2#184 (64c48be, "Gate every canister-reaching tool on the discoverability manifest") is now on imcp2 main. Reads are gated exactly like writes: get_canister_candid, get_canister_api_doc, get_canister_oql_schema, canister_query on both its paths and canister_update_call are all restricted to canisters a manifest declares. The module docs say "Reads and writes share one mechanism and differ only in what a refusal SAYS"; the_rule(), carried in every refusal, now reads "This server reads and calls ONLY canisters an app declares"; and READS_ARE_FINE — the constant that told agents canister_query and get_canister_candid worked regardless — is gone.

So the two suggested sentences ("the additional condition ICP MCP applies to state-changing calls", "It does not require manifest publication for metadata retrieval or query calls") were right when written, on exactly the evidence they cited, and are wrong now. I have overwritten that wording rather than leaving the guide telling operators their undeclared canisters stay readable. Revert me if you would rather handle it separately.

What survives from the suggestions is their substance: publication is sufficient, and registration is optional and not a condition of participation. What changed is where the line sits — no longer reads versus writes, but calls that reach a canister versus the surface that does not. open_app, the static guides and the identity tools reach no canister and stay ungated, which is why the caution still says an app publishing no manifest is resolved and described.

@sea-snake your approval was on 8ec933f, so this commit is newer than what you read. dfinity/internetcomputer-org#97 makes the matching correction to App Operator Terms §3, §4 and §7; that one should merge with or before this, since the Terms are the authority this page defers to.

npm run validate: 210 files, all checks passed.

---

Generated by Claude Code

[aterga]

Cross-checking this page against five wording defects found in review of the companion Terms change (dfinity/internetcomputer-org#97, fixed there in 056d03a). Four never applied here, because your suggested wording for the opt-in paragraph already avoided them:

Defect in the Terms	This page
"every call that reaches one of your canisters" over-generalised and contradicted the frontend-fetch carve-out	Not present. Your wording enumerates instead of generalising.
Gated operations named inconsistently, omitting metadata retrieval	Names all three: "retrieves canister metadata or invokes query or update methods"
"publishes none" ignored the invalid-manifest case	Already "missing or invalid"
"your gateway", "your frontend canister" assumed operator-controlled infrastructure	Not present
Removal described as immediate	Applies here too (below)

The fifth: this page ends "Removing the manifest blocks new metadata reads and query or update calls", with no qualifier. In the Terms that is now "once the Service observes the removal", because removal is not instantaneous from ICP MCP's side and an operator relying on it for incident response should know that.

I have not changed it here, for two reasons. It is your suggested wording, applied verbatim two commits ago. And the nuance is contractual rather than instructional: a guide telling a developer how to opt out reads worse for the hedge, whereas the Terms need it because an operator may rely on removal as a mitigation. If you want it aligned anyway, the minimal edit is:

> Once ICP MCP observes the removal, it blocks new metadata reads and query or update calls.

Your call. Everything else on this page matches the Terms as revised.

---

Generated by Claude Code

[aterga]

Both open questions answered and applied in 44607c2.

The observation qualifier, which was the fifth of the five defects found in review of the Terms and the only one that still applied here. The caution's last sentence is now:

> Once ICP MCP observes the removal, it blocks new metadata reads and query or update calls.

That matches App Operator Terms §4 and §7, which carry the same qualifier, and it matters to an operator who removes the manifest expecting an immediate cutoff.

The duplicated Layer 1 sentence is trimmed to a back-reference where it introduced the five-layer table; the caution keeps the full statement. Details on that thread.

npm run validate: 210 files, all checks passed.

The Terms side of this is now merged and live: internetcomputer-org#97 shipped as Version 1.1, effective September 2, 2026, and https://internetcomputer.org/icp-mcp/app-operator-terms/ serves the corrected §3, §4 and §7. So the dependency this page defers to is in place, and this PR is waiting only on a @dfinity/dx approval per .github/CODEOWNERS.

---

Generated by Claude Code