Skip to main content
Do this when something outside a browser needs to call AgentArea — a harness connecting to an MCP endpoint, a CI job starting a task, a script. Do not use these for a downstream MCP server’s own credential; that is the server’s secret, covered in Pass secrets to an MCP server. One token type covers the whole API. The same key authenticates /v1/mcp/{instance_id}/mcp, /client-mcp/{client_id}, task creation, and A2A.

​
Prerequisites

  • A browser session or an existing key with access to the workspace. Key management is behind normal authentication.
  • Somewhere to put the token immediately. The raw value is returned once.

​
Steps

1

Create a key

token appears in this 201 response and nowhere else. Only a SHA-256 hash is stored, so a lost token cannot be recovered — create a new one and revoke the old.Omit expires_in_days for a non-expiring key. Prefer an expiry for anything on a laptop or in a build.
2

Use it

Every endpoint takes the same bearer header. The aat_ prefix is what routes the token to API-key validation rather than JWT or OAuth verification.
For a harness, configure the endpoint from the client’s mcp_endpoint_url and this token together — see Combine several MCP servers behind one endpoint.
3

Audit what exists

token_prefix is the first 12 characters, which is how you identify a key without the secret. access_count and last_accessed_at tell you whether a key is still in use — check both before revoking one nobody claims.
4

Rotate

There is no rotate endpoint. Rotation is create-then-revoke, in that order:
Revocation is immediate — the key is marked inactive and validation refuses it on the next request. There is no grace period, so revoking before the new key is deployed is an outage.

​
Verify

Confirm the new key authenticates and that the old one no longer does.
A 200 then a 401 proves the rotation landed. You can also confirm the key is being exercised — access_count increments on use:

​
Troubleshooting

Check the prefix survived the copy. A token without the aat_ prefix is routed to JWT verification, fails there, and reports the same 401 as a bad key. Shell quoting that drops the underscore is the usual cause.
The key expired. expires_at is set at creation from expires_in_days and cannot be extended — PATCH is not supported on keys. Create a replacement.
The key authenticated but is not authorized for that client bundle, and because /client-mcp/{client_id} speaks MCP the refusal arrives as a JSON-RPC error rather than an HTTP 403. A workspace key is not automatically permitted to use a registered client; the principal needs the use relation on it, or the token’s subject must be the client itself.
Revocation sets is_active to false rather than deleting the row, so the audit trail survives. Filter on is_active when you want live keys.
DELETE takes the key’s id , not its token_prefix . Look up the id from the list first.
These keys carry the workspace access of the principal that created them; there is no per-endpoint or read-only scope on the key itself. Constrain what a consumer can reach with governance policy and, for MCP bundles, by curating the client’s member instances — not by scoping the token.

Combine several MCP servers behind one endpoint

Aggregate the tools of several MCP instances into a single namespaced endpoint by attaching them

Pass secrets to an MCP server

Declare which inputs are credentials with env_schema, supply their values on the instance

MCP

What the Model Context Protocol gives an agent, and how AgentArea hosts MCP servers
Last modified on September 17, 2026