Chatbots — Setup¶

Connect Prism to Claude Desktop or any other MCP-compatible chatbot in about two minutes. You paste a JSON block into your client's config file, restart the client, and verify the connection in the UI — no prompts to memorise, no commands to run. This guide covers the two transports the Prism gateway supports (the mcp-remote bridge and direct streamable-http), with platform-specific notes for Windows, macOS, and Linux.

Note: The JSON snippets in this guide mirror the prompts the Prism Console generates for users. The single source of truth is apps/prism-console/src/pages/settings/tokens/chatbot-prompts.ts in the Prism repo. If you edit this guide, also update the Console prompts — and vice versa.

When to read this¶

You have a Prism developer token from the Console and want to use Prism from Claude Desktop or another chatbot client.
Your client doesn't have a shell — so the prism CLI isn't an option.
A chatbot you've already configured suddenly shows "no MCP tools" or fails auth, and you need the troubleshooting playbook.
You're switching between Path A (the mcp-remote bridge) and Path B (direct streamable-http) and want to know which to pick.

If you have shell access and use a coding agent (Claude Code, Cursor, Windsurf, Codex, Devin, Antigravity), read Coding Agents — Setup instead — the CLI gives you overlay-aware reads and better unpushed-file freshness.

Canonical URLs¶

These are the only URLs you should reference in any client config. If your tenant uses a different gateway alias, the Console MCP config snippet will show the correct URL — use that one.

Surface	URL
Gateway (MCP endpoint)	`https://prism-gateway-xvsemyikqq-oa.a.run.app/mcp`
Console (token management, repo connection)	`https://prism-console-swisper.web.app`

Throughout this guide, YOUR_PRISM_TOKEN is a placeholder. Replace it with the literal token string from Console → Settings → Developer Tokens. Tokens never expire — treat them like API keys.

Claude Desktop¶

The primary chatbot client. Drop-in MCP config, no prompts to copy into Claude. You edit one file, restart Claude Desktop, done.

Step 1: Open the config file¶

In Claude Desktop: Settings → Developer → Edit Config.

This opens claude_desktop_config.json in your default editor on the canonical path for your OS:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Use Edit Config rather than opening the path manually — it guarantees you edit the file Claude Desktop actually loads. (Editing a path you typed yourself is the #1 onboarding footgun.)

If the file doesn't exist, create it with {}.

Step 2: Drop in the `prism-hosted` block¶

If mcpServers already has a prism-hosted entry, replace it — do not keep the old one alongside the new one. Stale entries (for example, pointing at a local prism-mcp-proxy.js) fail silently and block Prism.

Path A — `mcp-remote` bridge (recommended)¶

Claude Desktop talks to a local Node bridge over stdio; the bridge forwards to Prism's HTTPS endpoint. This is the path most users land on — it works on free, Pro, Team, and Enterprise plans, and on every Claude Desktop build that supports MCP at all.

Pick the block for your OS — the command value differs.

Windows (note npx.cmd, not npx — Claude Desktop on Windows launches command directly without a shell, so it can't resolve the npx shim):

{
  "mcpServers": {
    "prism-hosted": {
      "command": "npx.cmd",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://prism-gateway-xvsemyikqq-oa.a.run.app/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer YOUR_PRISM_TOKEN"
      }
    }
  }
}

macOS / Linux:

{
  "mcpServers": {
    "prism-hosted": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://prism-gateway-xvsemyikqq-oa.a.run.app/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer YOUR_PRISM_TOKEN"
      }
    }
  }
}

The Authorization:${AUTH_HEADER} + env pattern (no space after the colon) sidesteps a known mcp-remote argument-parsing issue on some platforms — do not "fix" this to add a space. Requires Node ≥ 18 on PATH; npx fetches mcp-remote on first launch.

Path B — Direct streamable-http (advanced / experimental)¶

If you've confirmed your Claude Desktop build advertises native remote-MCP support, you can skip the Node bridge and let Desktop speak streamable-http directly. Most builds (and all free-plan accounts at the time of writing) still need Path A — if Path B silently shows "no MCP tools available", switch back to Path A.

Windows, macOS, and Linux (same JSON — no platform-specific shim is needed because there's no local executable to launch):

{
  "mcpServers": {
    "prism-hosted": {
      "type": "streamable-http",
      "url": "https://prism-gateway-xvsemyikqq-oa.a.run.app/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_PRISM_TOKEN"
      }
    }
  }
}

Restart instructions¶

Save the file and fully quit Claude Desktop. Closing the window is not enough — Claude Desktop keeps running in the system tray (Windows) or menu bar (macOS). Right-click the tray/menu icon → Quit, then relaunch. Config is read at launch only.

Generic MCP clients¶

For any MCP-compatible client that isn't Claude Desktop (custom integrations, ChatGPT desktop, Gemini CLI, Continue, etc.). Paste into the client's MCP configuration. If a prism-hosted entry already exists, replace it — don't keep both.

Path A — stdio bridge via `mcp-remote` (recommended)¶

Most MCP clients today are stdio-only — they launch a local command and talk to it over stdin/stdout. The mcp-remote bridge runs locally, speaks stdio to the client, and forwards to Prism's HTTPS endpoint. Pick the block for your OS — the command value differs.

Windows (use npx.cmd, not npx — many Windows clients launch command directly without a shell):

{
  "mcpServers": {
    "prism-hosted": {
      "command": "npx.cmd",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://prism-gateway-xvsemyikqq-oa.a.run.app/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer YOUR_PRISM_TOKEN"
      }
    }
  }
}

macOS / Linux:

{
  "mcpServers": {
    "prism-hosted": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://prism-gateway-xvsemyikqq-oa.a.run.app/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer YOUR_PRISM_TOKEN"
      }
    }
  }
}

The Authorization:${AUTH_HEADER} + env pattern (no space after the colon) sidesteps a known mcp-remote argument-parsing issue on some platforms. Requires Node ≥ 18 on PATH.

Path B — Direct streamable-http (advanced / experimental)¶

If your client documents native remote-MCP support (HTTP request/response with Bearer auth), you can skip the Node bridge:

{
  "mcpServers": {
    "prism-hosted": {
      "type": "streamable-http",
      "url": "https://prism-gateway-xvsemyikqq-oa.a.run.app/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_PRISM_TOKEN"
      }
    }
  }
}

If the client silently shows no tools after Path B, fall back to Path A.

Notes for generic clients:

Transport at the gateway is streamable-http (HTTP request/response, no SSE). The endpoint is at /mcp.
Repo scoping is automatic for single-repo tenants. Multi-repo tenants pass repo="Owner/Repo" per tool call.
Claude.ai web does NOT yet support Bearer-token MCP auth — only OAuth. Use Claude Desktop or Claude Code instead.
If your client doesn't support remote MCP at all (and can't run mcp-remote either), file an issue at https://github.com/Fintama/swisper_prism/issues.

Restart and verify¶

After every config change, fully quit and relaunch the client. Then open Settings → Developer → MCP Servers in Claude Desktop — prism-hosted should appear with status Connected. That's the verification — no need to ask Claude anything.

For generic MCP clients without a built-in connection view, ask the chatbot to list the MCP tools it sees. You should get back Prism's tools (search_code, find_references, get_symbol_definition, get_module_map, etc.). If the list is empty, jump to Troubleshooting.

Troubleshooting¶

prism-hosted: Failed with MODULE_NOT_FOUND for some local .js file You have a stale prism-hosted entry from a previous setup (commonly the old prism-mcp-proxy.js config). Re-open Settings → Developer → Edit Config and confirm the block matches Step 2 exactly. The error log path tells you which file is being loaded — it should be the canonical path for your OS, not a path you typed by hand.

401 / "auth_failed" Your token is revoked, wrong tenant, or contains a stray newline/whitespace from a bad paste. Regenerate the token in the Console (Settings → Developer Tokens → Rotate) and replace the literal string in AUTH_HEADER (Path A) or in the Authorization header (Path B). Confirm there's no leading space and no surrounding quotes inside the value.

"Cannot find module 'mcp-remote'" (Path A) Retry — npx -y should fetch it on first launch. If retries keep failing (corporate proxy, offline machine), install globally with npm install -g mcp-remote and change command from npx/npx.cmd to mcp-remote directly (drop the -y and mcp-remote@latest args).

Path A "command not found" / silent exit Node ≥ 18 isn't on the PATH that Claude Desktop sees. On macOS, GUI-launched apps don't inherit your shell PATH — install Node via the official .pkg or use launchctl setenv PATH so the bundled npx is visible to GUI apps. On Linux, ensure the user account that launches Claude Desktop has Node ≥ 18 on its PATH.

Path B returns no tools Your Desktop (or client) build doesn't speak remote MCP natively. Switch to Path A — it works on every Claude Desktop build that supports MCP at all.

Multiple Claude Desktop installations If you've installed Claude Desktop more than once (e.g., a beta build alongside the main release), each installation may read a different config path. Always use Settings → Developer → Edit Config from the running instance — that guarantees you edit the file that instance loads. After saving, check the MCP Servers panel of the same instance.

Claude Desktop says "no MCP tools available" You're probably on Path B with a build that doesn't support it. Switch to Path A (mcp-remote bridge). Restart Claude Desktop fully (Quit, not just close) after every config change. Check the config is valid JSON — a missing comma or unmatched brace silently breaks the entire mcpServers block.

Still stuck Run the bridge from a terminal to capture verbose logs:

npx mcp-remote https://prism-gateway-xvsemyikqq-oa.a.run.app/mcp --header "Authorization: Bearer YOUR_PRISM_TOKEN" --debug

Logs land in ~/.mcp-auth/. The terminal run uses the regular shell PATH, so it tells you whether the bridge itself works independent of Claude Desktop's environment.

Note on Claude.ai (web)¶

The Claude.ai web UI does not currently support Bearer-token auth for custom remote MCP servers — only OAuth. Use Claude Desktop or Claude Code for now.

FAQ¶

Q: Path A vs Path B — which should I use?¶

A: Use Path A (mcp-remote bridge) unless you have a specific reason not to. Path A works on every Claude Desktop build and every Claude plan; Path B only works on recent builds that speak remote MCP natively. If you set up Path B and the MCP Servers panel shows no tools or the client says "no tools available", fall back to Path A — that's the diagnostic.

Q: Do my tokens expire?¶

A: No. Prism developer tokens never expire — they remain valid until you explicitly rotate or revoke them in the Console. Treat them like API keys: store them in a password manager, never commit them to a repo, and rotate them if you suspect leakage.

Q: Can I use this with multiple repos?¶

A: Yes. The same prism-hosted MCP entry serves every repo your tenant has connected. For single-repo tenants, the gateway scopes queries automatically. For multi-repo tenants, pass repo="Owner/Name" per tool call when the chatbot needs to disambiguate (the chatbot will usually do this on its own when you mention a repo by name). See Console Admin for connecting additional repos.

Q: The server says 401 — what's wrong?¶

A: Three common causes. (1) The token is revoked or belongs to a different tenant — rotate it in the Console. (2) Your paste introduced a leading space or trailing newline in the literal Bearer <token> string — re-paste cleanly. (3) You typed Authorization: ${AUTH_HEADER} with a space after the colon — remove the space, it sidesteps a known mcp-remote parsing issue. See the Troubleshooting section above for the verbose debug command.

Q: Do I need to install `mcp-remote` separately?¶

A: No. The Path A config uses npx -y mcp-remote@latest, which fetches the bridge on first launch and caches it. You only need Node ≥ 18 on the PATH that your chatbot client sees. If npx can't reach npm (corporate proxy, offline machine), install globally with npm install -g mcp-remote and change command to mcp-remote directly.

Q: Why is there an `env` block with `AUTH_HEADER` instead of just inlining `Bearer <token>`?¶

A: The env-var indirection works around a known mcp-remote argument-parsing issue: when the literal string Bearer <token> is passed as a CLI arg with a space, some platforms split it incorrectly. Passing Authorization:${AUTH_HEADER} (no space after the colon) and binding AUTH_HEADER in env keeps the value intact across every platform. Don't "fix" it to remove the env block — it will silently break on Windows.

Q: Can I use the Claude.ai web UI?¶

A: Not today. Claude.ai web supports OAuth-only for custom remote MCP servers; Prism uses Bearer-token auth. Use Claude Desktop, Claude Code, or the prism CLI instead.

Coding Agents — Setup — install the prism CLI for shell-equipped agents (Claude Code, Cursor, Windsurf, Codex, Devin, Antigravity) — gives you better unpushed-file freshness than chatbot MCP.
Console Admin — connect a repo, invite teammates, and manage developer tokens (where the token in AUTH_HEADER comes from).
Glossary — definitions of MCP, gateway, token, streamable-http, mcp-remote bridge, and other terms used here.

Chatbots — Setup¶

When to read this¶

Canonical URLs¶

Claude Desktop¶

Step 1: Open the config file¶

Step 2: Drop in the prism-hosted block¶

Path A — mcp-remote bridge (recommended)¶

Path B — Direct streamable-http (advanced / experimental)¶

Restart instructions¶

Generic MCP clients¶

Path A — stdio bridge via mcp-remote (recommended)¶

Path B — Direct streamable-http (advanced / experimental)¶

Restart and verify¶

Troubleshooting¶

Note on Claude.ai (web)¶

FAQ¶

Q: Path A vs Path B — which should I use?¶

Q: Do my tokens expire?¶

Q: Can I use this with multiple repos?¶

Q: The server says 401 — what's wrong?¶

Q: Do I need to install mcp-remote separately?¶

Q: Why is there an env block with AUTH_HEADER instead of just inlining Bearer <token>?¶

Q: Can I use the Claude.ai web UI?¶

Related¶

Step 2: Drop in the `prism-hosted` block¶

Path A — `mcp-remote` bridge (recommended)¶

Path A — stdio bridge via `mcp-remote` (recommended)¶

Q: Do I need to install `mcp-remote` separately?¶

Q: Why is there an `env` block with `AUTH_HEADER` instead of just inlining `Bearer <token>`?¶