Agents over MCP
An AI agent such as Claude Code can use the company through /mcp, an MCP server over Streamable HTTP. It serves clients of MCP 2026-07-28 and 2025-era clients alike, and keeps no session. The agent acts as the person the login names, so the policy decides each call and the ledger records it as theirs. On this machine the client names the person in the x-sanoma-actor header. For Claude Code, an .mcp.json entry:
{ "mcpServers": { "acme": { "type": "http", "url": "http://127.0.0.1:3000/mcp", "headers": { "x-sanoma-actor": "ada" } } }}To have the calls made by an agent on the person’s behalf, declare the agent in resources/people.ts (sanoma.agent({ id: "claude-code", client: "https://claude.ai/oauth/claude-code-client-metadata" }), People) and name it in the x-sanoma-agent header beside x-sanoma-actor (either may be URI-encoded): "headers": { "x-sanoma-actor": "ada", "x-sanoma-agent": "claude-code" }. Every tool call is then the agent’s acting for Ada: the policy sees the agent, in its groups and agents, with onBehalfOf Ada (so an @hold("on-behalf-of") waits for her), and is asked again as Ada alone, the stricter answer standing, so the agent may do no more than she may (People); get_run, the ledger, the run’s trace and the Inbox say claude-code for ada. A name that is not a declared agent (a person’s, one of the runtime’s own agents’, sanoma-chat, the app’s chat’s own, among them, a built-in client’s agent that no file declares, anyone undeclared), or an agent declared to act for someone else, is refused (403, not_admitted). Ada may approve a hold on a run her agent started for her. An agent starts none of the runtime’s own workflows but drift, which the policy decides for it (a forbid on workflow:drift for agents refuses it, not Ada). Without the header, the calls are the person’s, as above.
On a host, an MCP client signs in through the company’s own staff sign-in, which is an OAuth 2.1 authorization server for /mcp (Better Auth’s). The instance has one agent address, set by SANOMA_HOSTNAME, the hostname the app is served at over HTTPS: https://<hostname>/mcp, with the sign-in at https://<hostname>/auth/better-auth as its issuer. Without a hostname it is set by SANOMA_HOST_URL, the instance’s own URL: a Cloudflare host’s Worker has its workers.dev URL there, and an instance reached at a port, an IP address or over plain http names itself there (SANOMA_HOST_URL=http://10.0.0.7:3000). Tokens are issued for that address alone and the metadata names it, whatever host a request arrives on. With neither variable the sign-in serves no OAuth, which sanoma serve says once when it starts: /mcp still answers a signed-in person’s browser, and answers a client 401 with no challenge and an error that names both variables. Add the address to the client (claude mcp add --transport http acme https://acme.example/mcp). Its first request without a token gets a 401 whose WWW-Authenticate points at the resource’s metadata (https://<hostname>/.well-known/oauth-protected-resource/mcp, on a request that reached the app by another name too), which names the sign-in as its authorization server; the client then opens the sign-in in the person’s browser, where they sign in by email code as they do to the app (signed in already, they go straight on), and a consent page asks whether the client may act for them, as which agent; it is shown at every sign-in of a client that takes its answer on the person’s own computer (a loopback redirect, as Claude Code’s: any program there could ask in its name), and once for a client whose redirect is an HTTPS address of its own, whose later sign-ins skip it while it still stands for the same agent (mapped to another, the person is asked again, and the tokens the client holds are refused until then: they are for the agent consented to). The client gets an access token for that address’s /mcp alone, and each tool call is the agent’s acting for that person, exactly as with x-sanoma-agent above.
Claude’s clients are built in on every company, so they need no declaration. Each is known by the URL of its client ID metadata document and acts as a built-in agent, in the group agents, for the person who signed it in:
| Client | Client id | Built-in agent |
|---|---|---|
| Claude’s apps: claude.ai, Claude Desktop and Claude mobile | https://claude.ai/oauth/mcp-oauth-client-metadata |
claude-ai |
| Claude Code | https://claude.ai/oauth/claude-code-client-metadata |
claude-code |
The consent page names the built-in agent and says it is built in to Sanoma and that the company has not turned it off. A policy written for agents reaches a built-in agent as it reaches any agent, and one may name it (principal == Sanoma::Principal::"claude-code"), so a company can forbid or hold its calls by policy alone. sanoma check and the People page’s Agents tab list each built-in client and whether the company accepts it.
A company changes this in resources/people.ts, read at each request like the rest of the people:
// Claude Code acts as the company's own agent instead of the built-in one.export const claudeCode = sanoma.agent({ id: "claude-code", client: "https://claude.ai/oauth/claude-code-client-metadata", onBehalfOf: ada,});
// Claude's apps are turned off: refused as an undeclared client is.export const noClaude = sanoma.agent({ id: "claude-ai", off: true });- Replace it. An agent that declares a built-in client stands for that client, under any id, with its own groups and
onBehalfOf. The built-in agent then does not act. - Turn it off.
sanoma.agent({ id: "<the built-in agent's id>", off: true })turns that built-in off. The declaration is no agent, andoffon any other id, or beside aclientor anonBehalfOf, is a problemsanoma checkreports. - An id already taken. A person or an agent with a built-in agent’s id that does not declare its client keeps that id, and the built-in client is refused while it does;
sanoma checkwarns. Sosanoma.agent({ id: "claude-code", client: "claude-code" })still works on this machine as before, and Claude Code is refused on a host until the agent names the client’s URL.
Any other client is let in only as an agent resources/people.ts declares for it, by its client id (sanoma.agent({ id, client })). A built-in client turned off is refused the same way at authorize, the token endpoint and /mcp, with words that say it is turned off rather than where to declare it. A client no agent declares is refused when it asks to sign in, with a page that says where agents are declared and shows the client’s id, to declare only for a client you chose to connect yourself (a link anyone sends can name any client); a token is refused (403, not_admitted) as soon as its agent’s declaration goes or its built-in is turned off, and one for another host’s /mcp, expired or not this company’s is a 401 that sends the client to sign in again. A token is taken at /mcp alone, as Authorization: Bearer (the scheme in any case); a DPoP token is not one (the sign-in issues none), and gets the same 401. The client can end its refresh token itself (RFC 7009 revocation, with its client id alone); signing out of the app’s sign-in does not, since that grant is the client’s, not the browser’s. A browser with a signed-in session still reaches /mcp as the person. The x-sanoma-actor header means nothing on a host, and x-sanoma-agent is refused there (400). An API token (sca_…) acts as a visitor and is refused.
It has six tools, as the person or the agent acting for them, the same the app’s chat has (src/server/catalog.ts, one definition for both):
| Tool | What it does |
|---|---|
describe |
What sanoma.describe answers through POST /api/call: each of the company’s own workflows (name, api name, title, trigger, input as JSON Schema), each operation that may be called directly (id, effect, description, input and output) and each collection. It leaves out the runtime’s own workflows, which no tool starts, and the policy, file paths and source, the resources’ declared values, secret bindings, connections and the database’s host |
lookup |
Calls an operation that may be called directly and whose effect is read; any other is invalid_input. A call the policy holds is approval_pending, with the runId of its run |
get_run |
A run’s workflow, status, who started it, when, its approvals and its error |
wait_run |
Waits up to 20 s (waitMs) for the run to end: { runId, status: "finished", output }, or { runId, status: "running" } while it has not |
drift |
Starts the built-in drift, which reads each declared resource from its vendor and changes nothing, and answers as wait_run does. A company whose data files declare no resources has nothing to check: invalid_input, saying so |
start_run |
Starts one of the company’s own workflows, by the name or api name describe lists, with its input: { runId }. Any other name is invalid_input; the runtime’s own workflows, such as apply, are not started here |
start_run, drift and lookup take an optional id (letters, digits, _ and -, at most 200), as the app’s own calls send one. Send a new one for each call and the same one on a retry: a start or a drift with an id it already has answers that run (the run’s id is the id) when the workflow, input, person and agent are the same, and is refused (invalid_input) when they are not; a held lookup retried with its id is the same held run, so it files one approval.
/mcp only answers requests: a 2026-07-28 client’s subscriptions/listen is refused at once (JSON-RPC -32603), since the tools never change. A refusal of a tool call is a tool error whose structured content is the error body above, with its status. A visitor is refused (403), as is a request from a page on another site, told by its Sec-Fetch-Site or Origin header, so a page elsewhere cannot act with this browser’s name; a public site’s host has no /mcp (404). An MCP client sends neither header and needs no CSRF token.
These pages describe sanoma 0.11.24.