Connect a client

The desktop app does this for you. It detects which clients you have, writes the right file in the right shape, and tells you what was already configured on the machine. Use it unless you have a reason not to: statio.dev/download.

It also keeps them current. Every five minutes the app checks which servers you can use and updates each client it configured: a server you were just granted is added, one you lost access to is removed, and a file is only rewritten when something changed. Servers → Refresh syncs immediately. From a terminal, mcphub config sync does the same.

This page is the manual path: what the app writes, and where. Useful for headless machines, unsupported clients, or when you want to see exactly what changed.

Every MCP client connects the same way: one URL per server, and a credential that says who is calling. What differs is which file the client keeps its config in.

Who can call tools

Two kinds of caller can call tools, and each has its own credential:

<server-name> is the name shown on the server in the dashboard.

Agents

Create the agent under Settings → Agents, copy its client ID and secret (the secret is shown once), and grant it only the tools it needs.

The easy path: let mcphub hold the credential. It exchanges the secret, keeps it in the system keychain, and renews the token before it expires:

export STATIO_CLIENT_SECRET='<client secret>'
mcphub agent login --client-id <client id> --client-secret-env STATIO_CLIENT_SECRET
unset STATIO_CLIENT_SECRET
mcphub serve            # local proxy on 127.0.0.1:7777, signed in as the agent

Then point the client at http://127.0.0.1:7777/<server-name>/mcp, with no header. One mcphub sign-in is one identity per user account on a machine. To run several agents on one machine, give each its own HOME and --port.

Calling the gateway directly. Exchange the credentials for a token:

curl -s https://platform.romans.dev/api/v1/identity/agent-credentials \
  -H 'Content-Type: application/json' \
  -d '{"client_id":"<client id>","client_secret":"<client secret>"}'
# → {"access_token":"…","expires_in":…,"token_type":"Bearer"}

Send it as Authorization: Bearer <access_token> to https://api.statio.dev/<server-name>/mcp, and exchange again before expires_in runs out. A client config with a fixed header stops working when the token expires, so prefer mcphub serve for anything long-running.

Keep the client ID and secret in your platform's secret store (for example STATIO_CLIENT_ID and STATIO_CLIENT_SECRET), never in a config file in a repository.

Config file locations

Paths are macOS; Linux and Windows equivalents differ per client.

Claude Desktop

Claude Desktop's config file only accepts local (stdio) servers, so the app connects it through the mcp-remote bridge, which needs Node.js on the machine:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:7777/github/mcp"]
    }
  }
}

The URL is the app's local proxy, which holds your sign-in and attaches it to each request, so no key is written into the file. Restart Claude Desktop after the config changes; it reads the file only at launch.

The config

For a client that supports remote MCP servers, point it at the local proxy (a person signed in with the app, or an agent signed in with mcphub agent login):

{
  "mcpServers": {
    "github": {
      "url": "http://127.0.0.1:7777/github/mcp"
    }
  }
}

No header is needed: the proxy attaches the token. For an agent calling the gateway directly, use https://api.statio.dev/github/mcp with "headers": { "Authorization": "Bearer <agent access token>" }, and renew the token as described under Agents.

Add one entry per server. The key at the top ("github" here) is the name your agent sees; it does not have to match the server name in the URL, though keeping them the same saves confusion later.

Confirming it worked

Ask your agent to list its available tools. You should see the tools you were granted, not every tool the server exposes. That difference is the product doing its job.

Then check Audit in the dashboard. The listing itself is recorded, so a call that appears there confirms the whole path end to end.

When a tool is missing

Almost always a missing grant rather than a broken connection. Servers in the desktop app (or mcphub servers) shows every server in your organization, whether you can use it, and its tools. A server you can reach exposes only the tools you hold permission for; see Permissions.

If nothing at all appears, check in this order:

1. The session started after the server was installed. Clients load MCP servers at startup, so start a new session (in Claude Code, a fresh claude, not a resumed one) or quit and reopen the client.
2. The credential is one that can call tools: your device sign-in, or an agent's token. An API key gets "API keys cannot call tools".
3. For a person, you're signed in (mcphub whoami). For an agent, its token hasn't expired and its secret wasn't rotated or revoked.
4. The caller still has grants on that server.
5. The URL uses the gateway host (or the local proxy) and the server name is spelled right.