MCP integration
Connect Claude, Cursor, VS Code, and Windsurf to your Protobox tools via MCP
Every Protobox workspace exposes a managed MCP endpoint over streamable HTTP:
https://{workspace-slug}.protobox.app/mcp/srv/{server-slug}protobox mcp connect builds the right config block for your client and can write it for you —
no hand-editing JSON. Authentication is a server key (pbk_…), separate from your workspace
API key, sent as a standard bearer token:
Authorization: Bearer pbk_xxxxxxxxxxxxxxxxxxxxxxxQuick setup
1. Print the URL (optional — just to see it)
protobox mcp urlhttps://acme.protobox.app/mcp/srv/orders2. Connect a client
protobox mcp connect <claude|cursor|vscode|windsurf|raw>Run without -y/--yes first to preview — it prints the config block and where it would write,
but doesn't touch the file:
protobox mcp connect claudeClient: Claude Desktop
MCP server: orders (https://acme.protobox.app/mcp/srv/orders)
{
"mcpServers": {
"orders": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://acme.protobox.app/mcp/srv/orders",
"--header",
"Authorization:Bearer pbk_xxxxxxxxxxxxxxxxxxxxxxx"
]
}
}
}
Config file: /Users/you/Library/Application Support/Claude/claude_desktop_config.json
ℹ Not written (non-interactive) — add it yourself, or rerun with --yesAdd -y/--yes to write it:
protobox mcp connect claude --yes✓ Added orders → /Users/you/Library/Application Support/Claude/claude_desktop_config.json
ℹ Next: restart Claude Desktop, then ask it "what tools do you have?"Running it again merges into the existing mcpServers block rather than overwriting the
file, and backs up what was there first:
✓ Added orders → /Users/you/Library/Application Support/Claude/claude_desktop_config.json
ℹ Previous config backed up to /Users/you/Library/Application Support/Claude/claude_desktop_config.json.bak
ℹ Next: restart Claude Desktop, then ask it "what tools do you have?"A server key is minted automatically the first time you connect a client, unless you pass
--key <existing-key> to reuse one — see MCP keys below.
3. Restart the client, then test
protobox mcp testRuns a live handshake — initialize → tools/list — against the real endpoint, and reports
Handshake ok — N tools in Xms on success. A rejected key fails with:
✗ Error: MCP handshake failed
The key was rejected — mint a new one: 'protobox mcp keys create'Per-client config shapes
Each client wants a differently-shaped block. mcp connect <client> produces exactly what that
client expects — you never write these by hand.
Claude Desktop doesn't speak streamable HTTP directly — the config bridges through
mcp-remote, run via npx:
{
"mcpServers": {
"orders": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://acme.protobox.app/mcp/srv/orders",
"--header",
"Authorization:Bearer pbk_xxxxxxxxxxxxxxxxxxxxxxx"
]
}
}
}Written to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS).
Cursor connects directly over HTTP with a url + headers pair:
{
"mcpServers": {
"orders": {
"url": "https://acme.protobox.app/mcp/srv/orders",
"headers": { "Authorization": "Bearer pbk_xxxxxxxxxxxxxxxxxxxxxxx" }
}
}
}Written to .cursor/mcp.json in the current project.
VS Code uses a servers key (not mcpServers) and an explicit type:
{
"servers": {
"orders": {
"type": "http",
"url": "https://acme.protobox.app/mcp/srv/orders",
"headers": { "Authorization": "Bearer pbk_xxxxxxxxxxxxxxxxxxxxxxx" }
}
}
}Written to .vscode/mcp.json in the current project.
Windsurf uses serverUrl instead of url:
{
"mcpServers": {
"orders": {
"serverUrl": "https://acme.protobox.app/mcp/srv/orders",
"headers": { "Authorization": "Bearer pbk_xxxxxxxxxxxxxxxxxxxxxxx" }
}
}
}Written to .codeium/windsurf/mcp_config.json.
For any other MCP-conformant client — a generic url + headers block, printed to stdout
only, never written to a file:
protobox mcp connect raw{
"mcpServers": {
"orders": {
"url": "https://acme.protobox.app/mcp/srv/orders",
"headers": { "Authorization": "Bearer pbk_xxxxxxxxxxxxxxxxxxxxxxx" }
}
}
}All four target commands accept --server <slug> (only required when a workspace has more than
one MCP server) and --key <key> (reuse an existing server key instead of minting one).
MCP keys
Server keys are separate from your workspace API key — they authenticate the MCP endpoint itself, so you can hand one to a client without handing it your whole workspace credential, and revoke it independently.
protobox mcp keys create --name "claude-desktop"✓ Key created for 'orders'
Key: pbk_EXAMPLE_not_a_real_key
Prefix: pbk_DQfBwea7
! Warning: This is the only time the plaintext key is shown — store it now.
ℹ Next: protobox mcp connect claude --server orders --key pbk_EXAMPLE_not_a_real_keyprotobox mcp keys listID Prefix Last 4 Label Status Created
──────────────────────────────────────────────────────────────────────────────────────
6a7a95bff65a6055a0aa6527 pbk_DQfBwea7 KaUs claude-desktop active 2026-08-11T03:23:43.407Zprotobox mcp keys revoke 6a7a95bff65a6055a0aa6527✓ Revoked key '6a7a95bff65a6055a0aa6527'If a compromised key needs to be replaced, revoke it and reconnect the client — mcp connect
mints a fresh one and rewrites the config with --yes.
Scope with toolsets
By default the endpoint exposes your workspace's tools. For production, curate a toolset so each client only sees the tools it needs:
protobox toolsets create support --tool COINGECKO_PING --tool COINGECKO_SIMPLE_PRICE
protobox toolsets get support