Connect an agent

Any MCP client that speaks MCP over HTTP can connect to your workspace's hosted endpoint. This page covers the endpoint, access tokens, and client configuration. For the packaged Claude Code integration, see the Claude Code plugin.

Endpoint and authentication

Your workspace's MCP module in the app (the Connect tab) shows your endpoint URL. The server accepts MCP requests at POST /mcp and exposes an unauthenticated health check at GET /health:

curl -sS https://<workspace-mcp-host>/health

Every MCP request authenticates with a workspace access token in the Authorization header:

Authorization: Bearer mtt_<your-access-token>

There is no OAuth flow — the bearer token is the whole handshake. The workspace is resolved entirely from the token; clients never pass a workspace name or ID.

Issue and revoke tokens

Tokens are issued in the Tokens tab of your workspace's MCP module. Issuing requires the workspace admin or owner role. A token:

• looks like mtt_ followed by 64 hex characters;
• is shown exactly once at issue — copy it immediately, it cannot be retrieved later;
• can carry an optional expiry;
• can be revoked at any time from the Tokens tab.

Treat tokens like passwords: never commit them, never paste them into shared logs, and revoke any token that may have been exposed.

Claude Code

Register the endpoint with claude mcp add-json — this matches the snippet your Connect tab renders, with your endpoint and token filled in:

claude mcp add-json --scope user metatate '{"type":"http","url":"<mcp-server-url>/mcp","headers":{"Authorization":"Bearer <your-access-token>"}}'

Pasting a real token into a terminal command records it in shell history. The Claude Code plugin ships a helper that reads the token from an environment variable or a hidden prompt instead.

Any other MCP client

Configure an HTTP MCP server with the same three values — no Metatate-specific client code is needed:

{
  "type": "http",
  "url": "<mcp-server-url>/mcp",
  "headers": {
    "Authorization": "Bearer mtt_<your-access-token>"
  }
}

Once connected, the client's standard tool listing shows the seven tools described in the MCP server overview. You can also exercise every tool without wiring up a client at all: the Tools tab in the app previews calls using the same typed answer model as the live endpoint.

Security notes

• Tokens are hashed at rest; Metatate stores no recoverable copy.
• Missing, malformed, expired, revoked, and unknown tokens all produce the same unauthorized response — the server never reveals which.
• A token reads only its own workspace. Asset references from another workspace are indistinguishable from not found.
• Rate limits and plan quotas are enforced before tool work runs, with typed rate_limited and quota_exceeded errors.
• Errors use a closed, redacted code set and never include raw SQL, token material, policy prose, or credentials.

Answers describe published governance decisions and are advisory — see Typed answer states for how missing or conflicted state is reported.