Read the tool card live, and never let a live card widen scope

A tool server changes every time someone deploys it. Tools are added, renamed and removed, and their input schemas grow new fields. The authorization you granted at provisioning time does not change on its own. This post is about that gap: what to do when an MCP server's tool list changes and your authorization is per tool.

The card we trusted was out of date

When we provision a tool server, we publish a card for it in the service registry: its address, the tools it offers, and their schemas. Grants are written against that card. This agent may call this tool, on this server, for this job.

The orchestrator used the published card to decide what each server could do. That was fine on day one. By the second deploy it was wrong in both directions. New tools on the server were invisible to the orchestrator, so nobody could use them. Tools removed from the server were still on the card, and so were their grants. A grant for a tool that no longer exists is harmless until someone ships a new tool with the old name.

Live list, published ceiling

We split the job in two. The tool list is read live from the server by default, so the orchestrator always sees what the server really offers. The published card is the authorization ceiling. A live card can narrow what an agent may do. It can never widen it.

In practice that means a merge with rules:

• On the live list and on the card. Use the live metadata (description, schema) and the published grant.
• On the live list only. Visible as new, not callable, until someone approves a card update.
• On the card only. Not callable, and flagged for removal.

Before merging live metadata into the index, we check identity: same server address, same tool name. If either differs, we skip that tool with a warning instead of guessing. A tool that moved servers is a new tool.

1{2  "server": "claims-tools",3  "added": ["lookup_policy_history"],4  "removed": ["lookup_policy"],5  "changed": [6    {7      "tool": "create_note",8      "input": { "added": ["visibility"], "removed": [] },9      "output": { "added": [], "removed": [] }10    }11  ],12  "revokes": ["lookup_policy"]13}

Say what a refresh revokes, before the click

The approval step is where most of the care goes. When an operator refreshes a card, some tools disappear, and their grants go with them. That is the right behaviour. It can still surprise someone if the screen does not say so.

So the refresh shows the diff first, in plain words. Which tools are new. Which are gone. Which changed their inputs or outputs, field by field. And, as its own line, which grants this refresh will revoke. Then the operator approves. A person who does not write code should be able to read it and make the call.

This matters more than it looks. A schema change is a permission change in disguise. A tool that gains an optional field called visibility can now do something it could not do yesterday. If nobody reads that line, nobody approved it.

Update the card in place

One more thing broke as soon as we did this. The registry only supported publishing a new card, not updating an existing one. Every change was a re-publish, and a re-publish was a new identity. Enrolment and grants were tied to the old identity, so they were wiped each time.

The fix is an in-place card update that keeps the same identity. The card's content changes; who it is does not. Grants that still apply survive. Grants for removed tools are revoked by the diff, on purpose, with a record of who approved it and when.

What to take with you

• Read the tool list live. Treat the published card as the ceiling.
• A live card may narrow access. It must never widen it.
• Merge live metadata only for tools the card already has, with an identity check, or skip with a warning.
• Show what a refresh revokes before anyone approves it, and treat schema changes as permission changes.
• Update cards in place, keeping identity, so a schema change does not wipe enrolment.

Tools are permissions. Treat a new tool like a new permission, because it is one. The docs cover per-tool grants in more detail.