maisecrets / Sensitive References

Sensitive References for MCP

Running code first, protocol exploration second. maisecrets keeps some sensitive values out of the model context today. A separate, open design asks how MCP could do this for every server.

The problem

An MCP server can know a customer e-mail, an API key or a health identifier. An agent often needs that value in a later action, but it does not need to read it. Today the server usually sends the plaintext, and the plaintext goes into the model context. If the server redacts the value instead, the later action can fail. So a server that wants to protect PII in MCP has two bad choices.

The idea

The server sends an opaque reference instead of the plaintext. The model can carry, copy and route the reference. When an action needs the value, an authorized resolver outside the model puts the plaintext into the destination. The model gets back only the reference. Possession of a reference does not authorize its resolution.

The plaintext goes from the resolver to the destination only. The model can hold the reference, but the reference alone resolves nothing.

What maisecrets and mcpgate do today

Since mcpgate 2.0.3651 and maisecrets 0.8.14, the two use Sensitive References in Claude Code.

The AI sees a reference. mcpgate sends a reference with a short display, such as a masked e-mail address, instead of the value.
A command or a file gets the value. When Claude Code runs a command (Bash) or writes or edits a file, maisecrets puts the real value in. The AI does not see the value in the call. For one hour after a fetch, output that prints the value shows the reference instead.
A refused command gets nothing. If you refuse a command in Claude Code, maisecrets fetches no value.
The audit has no value. For a fetch, the gateway writes an audit row with the time, the kind of target (a file or a process) and a hash of each reference. The row never holds the value. From mcpgate 2.0.3756, the gateway gives no value if it cannot write this row.

Turn it on. Sensitive References are experimental. The administrator of your gateway turns them on for an allow list of users. Each time a program signs in, the gateway asks the user in the browser. The page names the program, its local address and the time. It needs mcpgate 2.0.3651 or later and maisecrets 0.8.14 or later.

Sign out one program. On the Connections page of the gateway, the list “Sensitive References: signed-in devices” shows each program that can fetch values for you. Revoke one, and it is signed out at once. An administrator can do the same for a user. The question at every sign-in and this list need mcpgate 2.0.3756 or later.

Limits. We tested Sensitive References in Claude Code only. A file then holds the real value in plain text: keep it where you would keep the value itself. If the AI reads the file later, it sees the value. The gateway gives at most 100 references in one call and 1,000 values per user per day.

Vault references. Sensitive References replace the older vault references after a transition. Until then, vault references keep working.

maisecrets is one implementation informing the design. The draft separates the protocol from the product: the mechanics of maisecrets are not proposed as core requirements.

What the design explores

The draft defines a text reference that fits ordinary string schemas, and it keeps the issuer of a reference in the host. It names the cases that must fail closed: a forged, unknown, ambiguous, revoked or expired reference. Its Python prototype tests these cases and one OAuth resolver profile with Keycloak. The prototype does not prove that hosts interoperate. Host support for durable provenance is the largest open risk.

Take part

The design is open for review. Read the draft and the open questions in the Sensitive References repository, and give feedback there.