Docs

Use Switchy from Claude Desktop, Cursor, or any MCP client

Switchy is also an MCP server. Drop one snippet into your client's config, paste a key, and your team's shared memory + Spaces show up inside the LLM you already use. This is in addition to the Switchy web app, not a replacement.

1. Add this to your client

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "switchy": {
      "transport": "http",
      "url": "https://switchy.build/mcp/rpc",
      "headers": {
        "Authorization": "Bearer sk_live_..."
      }
    }
  }
}

Replace sk_live_... with the key you mint below. Restart Claude Desktop after editing the file.

2. Mint a key

Open Settings → API Keys and click Mint MCP key. Switchy will create a key with all the MCP scopes for your current org and show it to you once. Copy it into the snippet above where it says sk_live_....

The key is org-scoped. If you switch to a different organization in Switchy, mint a separate key for that org.

3. Try it

Open Claude Desktop (or your client). Ask it something like "Use search_memory to find what we decided about deploys." If everything is wired correctly, the model will call the Switchy tool and stream the result back.

Quick test before plugging into a client

From a terminal: curl -X POST https://switchy.build/mcp/rpc -H "Authorization: Bearer YOUR_KEY" -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

A 200 with a list of tools means you're live.

What you can do

search_memory— Find relevant team knowledge.

"Use search_memory to find decisions about our deploy strategy."

list_spaces— See what Spaces (channels) exist in the org.

"List all the Spaces in my Switchy org and tell me which ones are most active."

get_space— Get one Space's details and recent sessions.

"Open the launch-readiness Space and summarise the last three sessions."

list_sessions— List sessions inside a Space.

"Which sessions in the platform Space had activity this week?"

get_session_transcript— Read the full message transcript of one session.

"Pull the transcript of session abc123 and find unresolved questions."

add_memory— Save a decision the team should remember.

"Remember for the org: we picked Ably for realtime in April 2026."

post_message— Send a message into a Switchy session as a teammate.

"Post this code review to the platform Space as me."

Posting messages on a teammate's behalf

By default a Switchy MCP key acts as the organization. It can read and write team memory, but it cannot post messages as a specific human.

To let a key call post_message, mint it with the act_on_behalf scope and add the header X-Switchy-Actor-User-Id: USER_ID on each call. The user id must belong to a member of the same organization.

Heads up

The first time a key posts a message on someone's behalf, every org OWNER gets an email with a revoke link. This is by design. If a key is misconfigured or shared, the people who can do something about it find out immediately.

Troubleshooting

401 Unauthorized: The bearer token was missing, malformed, revoked, or not org-scoped. Mint a fresh key from /settings.
403 Forbidden: The key is valid but is missing the scope this tool needs (or you sent the actor header without act_on_behalf). Edit the key's scopes in Settings.
404 Not Found: The Space, session, or memory you asked for doesn't exist OR your key isn't allowed to see it. Switchy returns 404 in both cases on purpose, so we don't leak the existence of resources outside your org.
429 Too Many Requests: Read tools are capped at 60/minute per key, write tools at 20/minute. The error envelope includes retryAfterMs; back off until then. If you're consistently hitting this, mint a second key for a separate workload.
My client says "tools not loaded": Confirm the snippet is in the right config file and the bearer is on the same line. Then run the curl test above. If the curl works but the client doesn't, restart the client. Most MCP clients only re-read config at startup.

Looking for the other side — connecting external tools like GitHub or Notion into Switchy? Connect external tools to Switchy →

Need help? Email support. The full machine-readable spec lives at /api/mcp/openapi.json.