Connect an MCP client

Stav runs an MCP server. An agent connected to it can read your models, keys, Routers, usage and billing, and act on them with your permissions — the same things you can do in Your workspace.

The fastest way to connect Claude Code, Codex, Cursor or Hermes is one setup prompt: see Set up your agent. This page is the manual setup for any MCP client.

1. Enable MCP for the workspace

An Owner or Admin opens Your workspace → Connect → MCP Server and enables MCP. The page then shows the Connection URL:

https://stav.ai/mcp

The same page shows how many tool calls the workspace has made.

2. Add the server to your client

Paste the URL into your client as a remote (Streamable HTTP) MCP server. For Claude Code:

claude mcp add --transport http stav https://stav.ai/mcp

3. Sign in

The client opens a browser to sign in to Stav. You do not paste a secret: the server supports OAuth dynamic client registration, authorization code with PKCE (S256), and refresh tokens. Discovery is at https://stav.ai/.well-known/oauth-authorization-server.

The agent acts as you. Anything your role cannot do in Your workspace, the tool call cannot do either.

More than one workspace

If you belong to more than one workspace, the agent asks which one to work in before its first workspace tool call. It never picks one for you. It then passes that workspace's slug as workspace on each call, for the rest of the conversation, and every result ends with Workspace: <name> (<slug>). workspaces_list shows your workspaces and their slugs.

Each conversation keeps its own choice, so two conversations can work in two workspaces at the same time over the same connection. To change workspace, tell the agent.

A client that can set headers can instead pin the whole connection to one workspace with an X-Team-Id header (the workspace id). A pinned connection refuses a workspace that names another one.

An inference tool given a Stav API key (an api_key argument, or an X-Stav-Api-Key header on the connection) runs in that key's workspace, so it takes no workspace, and that workspace's MCP switch and Read-only decide whether it may run.

Tools that call the inference API

Most tools use your sign-in. The inference tools — inference_chat, inference_models_list, inference_models_get, messages_create, messages_count_tokens, decisions_create — call api.stav.ai, which is billed per key. You do not need to create a key for them: Stav mints a hidden key for your sign-in and workspace the first time an agent calls one. It lasts 24 hours, bills the workspace wallet at catalogue price, and shows in Requests as "MCP". It never appears in the conversation. The workspace MCP switch and Read-only apply to it like to every other tool.

inference_chat, messages_create and decisions_create return the provider's body unchanged plus a stav block: the request id, the model and Inference Provider that served it, the compute country, the sovereignty level and the Smart Router's reason — the same facts the gateway sends as X-Stav-* response headers. The cost of a request is not in a header; request_routing_get with the request id gives it.

To bill a specific key instead, give it one of two ways:

• once per connection, as an X-Stav-Api-Key header on the MCP server URL, or
• per call, as the tool's api_key argument. Note that a key passed as an argument is part of the conversation, so prefer the header where your client can set one.

Turn MCP off, or make it Read-only

Two workspace settings on the same page control what agents may do. Stav checks both before every tool call. Only an Owner or Admin can change them.

• MCP off: every tool call is refused. Nothing runs. Turning it on again restores your settings.
• Read-only (under Tool Access Level): agents can call read tools only. Every tool that changes something, such as apikeys_create, is refused.
• Read & Write: agents can call every tool your role allows.

A change reaches every connected agent within about 15 seconds. You do not need to reconnect.

A refused call comes back as a tool error with the reason in plain text, for example:

This workspace's MCP access is Read-only, so 'apikeys_create' cannot run.

The refused call never reaches the rest of the platform.

Limits

The server allows 100 requests a minute per workspace by default. Over the limit it returns 429 rate_limit_exceeded, with X-RateLimit-Remaining and X-RateLimit-Reset headers.

Where calls show up

Tool calls that change something land in Your workspace → Govern → Audit log with origin mcp.