Agent Connections

The Connected Apps page shows the AI agents that you have authorized to access Switchbench through the MCP (Model Context Protocol) server. Each agent you sign in, such as Claude Code, Codex, claude.ai, or Cursor, gets its own connection. The agent works in the one organization you choose when you sign in, with the permissions you allow it, limited to the scopes your role in that organization grants. It does not receive a separate organization credential.

Agent connection vs. API key

An agent connection and an API key authenticate different things:

	API key	Agent connection
Used for	Direct REST transaction calls from your fintech backend or test harness	MCP tool calls by an AI agent you authorize
Credential	An opaque sk_live_… token	A short-lived OAuth access token issued after interactive sign-in
Access	API key scopes	The scopes your role grants in the organization you chose at sign-in, limited to MCP-supported scopes

Use an agent connection when you want an AI agent to work with Switchbench resources through MCP. Use an API key when your own application needs to call the transaction API.

Sign in to an agent

An MCP-capable agent signs in with the Authorization Code flow with PKCE (S256). It identifies itself to Switchbench in one of three ways:

• Its own client metadata document. Current agents, such as Claude Code and claude.ai, publish an HTTPS document that names the agent and lists its callback addresses, and use that document’s URL as their client ID. You give the agent only the MCP endpoint; no client ID is needed.
• Switchbench’s pre-registered public client. Agents that do not support client metadata documents are configured with the pre-registered client ID from the agent authentication guide.
• Dynamic client registration. An agent that supports RFC 7591 registers itself with POST /oauth/register before it signs in. This is on by default, and the agent needs no client ID from you.

When you connect, your browser opens and:

1. You sign in to Switchbench as yourself.
2. You choose which organization the agent may work in. If you belong to only one, it is already selected.
3. You review the permissions the agent is asking for. Each one is a checkbox that starts ticked. Untick any permission you do not want the agent to have, then select Allow. At least one permission must stay ticked.

For an agent that identifies itself with a client metadata document or registers itself, the consent page shows the name the agent gives itself and the host of its document (or, for a self-registered agent, the host of its redirect address), and notes that Switchbench has not verified the agent. It also shows the address that will receive the sign-in result. Allow access only if you recognise both.

The agent then receives access scoped to that organization, limited to the permissions you kept ticked and to those your role there grants. It keeps that organization when its access is renewed, and keeps those permissions until you edit them. To work in a different organization, remove the agent and sign in again. Switchbench does not issue a separate client secret for an agent connection.

See the agent authentication guide for the current authorization server metadata, client configuration, and MCP endpoint. The MCP server advertises its supported flow through the agent_auth discovery metadata.

Non-production environments use a single-level environment prefix on the host — for example https://test-mcp.switchbench.com/auth.md.

Connect from claude.ai

Agents that run on your computer, such as Claude Code, receive the sign-in result on a local http://localhost address. claude.ai runs the sign-in on Anthropic’s servers instead, and Switchbench accepts its callback address too. To add Switchbench as a claude.ai custom connector:

1. In claude.ai, open Customize → Connectors and select Add custom connector. On a Team or Enterprise plan, an Owner adds it once under Organization settings → Connectors (Add → Custom → Web), and each member then connects to it.
2. Enter a name and the MCP endpoint, https://mcp.switchbench.com/mcp, as the MCP server URL, then select Continue.
3. For Authentication, choose Sign in now and leave the OAuth client settings at their defaults: claude.ai identifies itself with its own client metadata document (see Sign in to an agent).
4. Select Add, then Connect. Sign in, choose an organization, and allow access as above. The consent page tells you the agent is hosted by a third-party service.

Connect from Cursor

Cursor’s built-in sign-in returns to a cursor:// address, which Switchbench does not accept. Cursor instead connects through the mcp-remote bridge, which needs Node.js 22 or later and receives the sign-in result on http://localhost:33418, using the pre-registered client ID:

1. In the dashboard, open Connect AI agent → Cursor and select Add to Cursor, then Install in Cursor. Or add the server to ~/.cursor/mcp.json yourself:

   {
     "mcpServers": {
       "switchbench": {
         "command": "npx",
         "args": [
           "-y",
           "mcp-remote",
           "https://mcp.switchbench.com/mcp",
           "33418",
           "--static-oauth-client-info",
           "{\"client_id\":\"<client-id>\"}"
         ],
         "env": {
           "MCP_REMOTE_CONFIG_DIR": "${userHome}/.mcp-auth/cursor"
         }
       }
     }
   }

   Replace <client-id> with the pre-registered client ID from the agent authentication guide. MCP_REMOTE_CONFIG_DIR gives Cursor its own sign-in cache, so it does not reuse a session another mcp-remote agent, such as Codex, already holds.

2. When Cursor first starts the server, your browser opens. Sign in, choose an organization, and allow access as above.

3. Check Cursor Settings → MCP: switchbench shows as enabled with its tools listed.

Review your connected agents

Open Connected Apps in the dashboard to see the agents you connected in the active organization. Each row shows where the agent runs (for example claude.ai, or localhost for an agent on your computer) or, for an agent that signed in with a client metadata document or registered itself, its name and the host of its document or redirect address. Each row also shows a summary of its permissions, when you connected it, and when it last renewed its access. Hover the permissions summary to see the full list.

Edit an agent’s permissions

Select Edit permissions on an agent’s row. The dialog lists every permission an agent can hold, with the same labels as the sign-in consent page, and ticks the ones this agent has now. Tick or untick permissions, then select Save permissions. At least one permission must stay ticked; to cut an agent off completely, remove it instead.

You can choose only from the permissions the agent asked for when it signed in. Others are greyed out, because an agent’s access can be narrowed but never widened beyond its sign-in. To grant one of them, remove the agent and connect it again. For an agent connected before this check existed, Switchbench knows only its current permissions, so you can remove permissions from it but not add new ones.

The change applies the next time the agent renews its access token, within about an hour. An agent never receives more than your role in the organization allows, even if you tick a permission your role does not have. Editing one agent does not change your other agents.

Remove an agent

Select Remove on an agent’s row to disconnect only that agent. Its next token renewal fails, and your other agents keep working. Its current access token stays valid until it expires, so removal takes full effect within about an hour.

To disconnect every agent at once, select Disconnect all agents. This removes each agent in the list and also revokes the shared authorization for your Switchbench account, so it applies to all your organizations. Each agent must sign in again to reconnect.

Access and scopes

An agent can call an MCP tool only when the access token contains the scope that tool requires. The token is based on your own organization role and on the permissions you allow it on the Connected Apps page. Within those scopes, an agent can create API keys and issue client certificates through their MCP tools, but it cannot change its own permissions or manage organization membership through MCP. Ask an organization administrator to update your role if you need access to additional tools.

Available tools

The agent only sees the tools its token has scopes for. A tool that lists two scopes needs both.

Tool	What it does	Scopes needed
get_usage	Get usage summary	usage:read
get_audit_log	Get audit log	audit:read
list_api_keys	List API keys	apikeys:read
create_api_key	Create API key	apikeys:write
revoke_api_key	Revoke API key	apikeys:revoke
rotate_api_key	Rotate API key	apikeys:revoke, apikeys:write
get_engine_config	Get engine config	engine:read
update_engine_config	Update engine config	engine:read, engine:config:write
save_routing_rule	Create or update a routing rule	engine:rules:write
list_kms_keys	List KMS keys	keys:read
rotate_kms_key	Rotate a KMS key	keys:rotate
issue_certificate	Issue a client certificate	certs:issue
revoke_certificate	Revoke a client certificate	certs:revoke
list_behaviours	List behaviours	behaviours:read
get_behaviour	Get a behaviour	behaviours:read
create_behaviour	Create a behaviour	behaviours:write
update_behaviour	Update a behaviour	behaviours:write
delete_behaviour	Delete a behaviour	behaviours:delete

Every tool works only in the organization you chose at sign-in; none takes an organization ID. This is a different server from the docs MCP server, which serves only the public documentation and needs no sign-in.

Troubleshooting

• If the agent cannot connect, check that it is configured with the Switchbench MCP endpoint from the agent authentication guide.
• If the browser sign-in never returns to Claude Code, Codex, or Cursor, make sure nothing else is listening on the callback port (33418 in the dashboard’s commands), then authenticate again.
• If Logto does not show a sign-in prompt, select Disconnect all agents in Connected Apps and start the authorization flow again.
• If a tool returns an authorization error, check the agent’s permissions in Connected Apps, and confirm that your role in the organization you chose at sign-in has the scope required by that tool.
• If sign-in ends with “not a member of any Switchbench organization”, ask an organization administrator to invite you first.
• If you remove an agent or edit its permissions but it still behaves as before briefly, wait for its existing access token to expire.