Setup guide

Connect Switch to your AI.

Switch runs a hosted MCP server — there is nothing to install and no server to run. Add one endpoint to your AI client, sign in once, and it can browse your library, check your balance, and create images and video right from the chat.

The only endpoint you need

https://www.switchapp.ai/mcp

Use this exact URL in every client below. It is both this website and the machine endpoint — your browser sees a page, your AI client sees the MCP server.

Claude (web — claude.ai)Claude Desktop Claude Code (CLI)Codex (CLI)Cursor ChatGPT connector

How sign-in works

Switch uses a standard OAuth handshake — your client never stores your Switch password. After you add the endpoint, the first time your AI uses a Switch tool it opens a Switch sign-in page in your browser. Approve access, and your client stores a token that refreshes quietly from then on. There is no API key to copy for the connector — the public connector is OAuth only.

The one trick that fixes most sign-in problems

After you approve access, the browser tab may show a “can’t reach localhost” or “MCP CLI Proxy” error. Do not close it. Copy the entire URL from the address bar — it looks like http://localhost:PORT/callback?code=…&state=… — and paste it back to your assistant / client to finish login. The page failing to load is normal in remote or sandboxed sessions; the code in that URL is still valid.

Set up your client

Claude (web — claude.ai)

The fastest setup. One custom connector, sign in once.

1
In the claude.ai sidebar open Customize, then Connectors. (Anthropic moved this out of Settings — if a guide says "Settings → Connectors", it now lives under Customize → Connectors.)
2
Click Add, then Add custom connector.
3
Name it Switch and paste the endpoint as the Remote MCP server URL:
Remote MCP server URL
```
https://www.switchapp.ai/mcp
```
4
Click Add, then Connect. A Switch sign-in page opens — sign in with your Switch account and click Allow.
5
Done. The connector shows a checkmark and lists the Switch tools. Ask Claude "use switch to list my images" to confirm.

Claude's Add custom connector dialog: Name set to Switch, Remote MCP server URL set to https://www.switchapp.ai/mcp.

Claude Desktop

Native connector — no bridge, no terminal.

1
Easiest: Settings → Connectors → Add custom connector, set the URL below and type HTTP, then Save and Connect.
Server URL
```
https://www.switchapp.ai/mcp
```
2
No "Add custom connector" button? Edit the config file instead and restart Claude Desktop:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json
```
{
  "mcpServers": {
    "switch": { "type": "http", "url": "https://www.switchapp.ai/mcp" }
  }
}
```
3
When it asks you to sign in, complete the browser OAuth step (see "How sign-in works" below). Avoid the npx mcp-remote bridge — use the native HTTP connector above.

Claude Code (CLI)

Add once at user scope, then sign in inside a session.

1
Add the server (user scope makes it available in every project):
Terminal
```
claude mcp add --transport http -s user switch https://www.switchapp.ai/mcp
```
2
Start a session and trigger a Switch tool. Claude Code opens the browser for the OAuth sign-in.
3
Confirm it connected:
Terminal — expect: switch ✔ Connected
```
claude mcp list
```
4
Need a clean slate? Remove it with:
Terminal
```
claude mcp remove switch
```

Codex (CLI)

Add an HTTP MCP server to your Codex config.

1
Add this block to ~/.codex/config.toml:
~/.codex/config.toml
```
[mcp_servers.switch]
url = "https://www.switchapp.ai/mcp"
```
2
Restart Codex so it loads the new server. (Some Codex builds also want an explicit transport line — add transport = "http" under the same block if the server doesn't show up.)
3
Trigger a Switch tool and complete the browser OAuth sign-in. If the redirect tab shows an error, use the callback-URL recovery trick below. (If your Codex build only supports local stdio servers, run an MCP HTTP bridge and point Codex at it — but prefer a client with native remote-MCP support.)

Cursor

Add an HTTP MCP server, global or per-project.

1
Add Switch to your Cursor MCP config — ~/.cursor/mcp.json for all projects, or .cursor/mcp.json inside one project:
~/.cursor/mcp.json
```
{
  "mcpServers": {
    "switch": { "url": "https://www.switchapp.ai/mcp" }
  }
}
```
2
Open Cursor → Settings → MCP, enable Switch, and sign in with your Switch account (OAuth) when prompted.

ChatGPT connector

Requires a paid ChatGPT plan with Developer mode enabled.

1
In ChatGPT, open Settings → Connectors → Advanced, and turn on Developer mode (needed for custom MCP servers).
2
Back in Connectors, choose Create / Add custom connector.
3
Name it Switch, set the MCP server URL below, and choose OAuth for authentication:
MCP server URL
```
https://www.switchapp.ai/mcp
```
4
Save, then open the connector in a chat and sign in with your Switch account when prompted.

Troubleshooting

› Error -32001 / "Unauthorized"

Switch returns JSON-RPC -32001 with the message "Unauthorized" when a tool call needs sign-in — just complete the OAuth login. Note: some clients also show -32001 for their own request timeouts, so check the message text: "Unauthorized" means sign in; "timed out" means wait a moment and retry a small call (like list or balance).

› It says the token expired / "requires re-authorization"

A session that started with an old token keeps failing every call. Re-run the connect / sign-in flow to get a fresh token, then fully quit and reopen your client so it loads the new token.

› Connector is stuck — only "Disconnect" shows, no "Reconnect"

Disconnect (or remove the server), add it again with the same URL, sign in again, and restart the client. Key gotcha: a running session will not pick up a token you refreshed in another window — after re-authenticating, fully restart the client so it loads the new token.

› Login keeps failing in a loop (corrupt cached token)

For CLI / bridge setups, clear the cached auth — rm -rf ~/.mcp-auth on macOS/Linux, or delete %USERPROFILE%\.mcp-auth on Windows — then restart and sign in again. Native desktop connectors manage their own tokens internally, so for those just remove and re-add the connector rather than hunting for files.

› I see the tools but every call fails

Listing the tools needs no login (that is why you can see them). The first tool CALL is what triggers the sign-in prompt. Complete the OAuth login and retry.

› Tools never appear after adding the server

Double-check the URL is exactly https://www.switchapp.ai/mcp, that you restarted the client after editing any config file, and that the config file is valid JSON/TOML (a stray comma silently disables every server). Then try a lightweight call like check balance first.

› Request timed out

A timeout means the request reached the server but no answer came back in time — it is not an auth failure. For big jobs (image/video), the job usually keeps running on Switch, so ask to show your last image or list your recent generations instead of re-firing the slow call. For quick calls (list/balance), wait a minute and try one lightweight call first; check that the Switch website itself loads in a browser; and avoid hammering retries — each one just burns time.

› Still stuck after a clean restart, fresh sign-in, and cleared cache

Run the pre-flight check: the URL is exactly https://www.switchapp.ai/mcp, you restarted the client after any config change, and the config file is valid JSON/TOML (one stray comma silently disables every server). If all of that is true and it still fails, the problem is likely server-side — check Switch status and contact support; no client config can fix an unreachable server.

Verified endpoint matrix

Several addresses reach the server, but always use the canonical one.

Address	Use it?
`https://www.switchapp.ai/mcp`	✓ Canonical — paste this into every client. Verified live as a working connector.
`Other (legacy) addresses`	✕ A few older addresses still answer the server, but do not use them — always paste the canonical URL above.