@spocapp/mcp-bridge

@spocapp/mcp-bridge

A ~200-line stdio ↔ HTTP+SSE bridge for the SPOC MCP server.

Claude Desktop, Cursor, Zed, Windsurf and most other MCP clients today only speak the stdio transport (JSON-RPC over stdin/stdout). SPOC's MCP server at https://spoc.com/mcp/rpc speaks HTTP+SSE. This bridge is the shim between the two: install it, point your MCP client at it, and SPOC's tools show up.

Install

Coming to npm shortly. For now:

git clone https://github.com/SPOC-App/spoc-mcp-bridge.git
cd spoc-mcp-bridge
npm install
npm run build
npm link

Once released:

npm install -g @spocapp/mcp-bridge

Configure your MCP client

Claude Desktop

Edit the config file:

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

{
  "mcpServers": {
    "spoc": {
      "command": "spoc-mcp-bridge",
      "env": {
        "SPOC_BEARER": "spk_live_...",
        "SPOC_ENDPOINT": "https://spoc.com/mcp/rpc"
      }
    }
  }
}

Restart Claude Desktop. SPOC's tools should appear in the tool picker.

Cursor

~/.cursor/mcp.json (or Settings → MCP → Edit mcp.json):

{
  "mcpServers": {
    "spoc": {
      "command": "spoc-mcp-bridge",
      "env": { "SPOC_BEARER": "spk_live_..." }
    }
  }
}

Zed

~/.config/zed/settings.json:

{
  "context_servers": {
    "spoc": {
      "command": {
        "path": "spoc-mcp-bridge",
        "args": [],
        "env": { "SPOC_BEARER": "spk_live_..." }
      }
    }
  }
}

Environment variables

Variable	Default	Notes
SPOC_ENDPOINT	https://spoc.com/mcp/rpc	HTTP JSON-RPC endpoint
SPOC_EVENTS_ENDPOINT	https://spoc.com/mcp/events	SSE endpoint for server-initiated notifications
SPOC_BEARER	(unset)	Token to send as Authorization: Bearer …. Omit for anonymous access
SPOC_TIMEOUT_MS	30000	HTTP request timeout
SPOC_DEBUG	(unset)	Set to 1 to log to stderr
SPOC_DISABLE_SSE	(unset)	Set to 1 to skip the SSE event stream

Bearer tokens

Generate one at https://spoc.com/settings/api-keys. Make sure the harness:issue scope is checked or SPOC will reject calls that need to issue harnesses.

Troubleshooting

Tools don't appear in Claude / Cursor / Zed after restart. Run spoc-mcp-bridge directly in a terminal and pipe a request in:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | spoc-mcp-bridge

You should see a JSON response listing every tool. If you get a JSON-RPC error frame, the error.data field will tell you why.

401 errors. The bearer token is missing, wrong, or lacks scope. Verify at https://spoc.com/settings/api-keys.

SSE won't connect. Notifications are optional. Set SPOC_DISABLE_SSE=1 and everything except server-initiated notifications will still work. If you want to debug, set SPOC_DEBUG=1 and watch stderr.

Testing

npm run build
npm test        # unit + client-integration suites (offline, no network)

The client-integration suite spawns spoc-mcp-bridge as a real subprocess and drives it through the same stdio protocol that Claude Desktop, Cursor, Zed, and Windsurf use — initialize, notifications/initialized, tools/list, tools/call, concurrent in-flight calls, mixed-type ids, SSE notifications, upstream errors, and timeouts. If it passes, MCP clients that speak stdio will work.

To also exercise the real production endpoint:

SPOC_LIVE_TEST=1 npm test                              # anonymous only
SPOC_LIVE_TEST=1 SPOC_BEARER=spk_live_... npm test     # + tools/call

CI runs the offline suite on Node 18 / 20 / 22 for every push and PR; the live suite runs on main only.

Writing your own client

If you're implementing SPOC's report-event HMAC signing directly (rather than going through this bridge), one thing to watch out for: SPOC's canonical form matches JavaScript JSON.stringify behaviour, which leaves non-ASCII characters as themselves rather than escaping them to \uXXXX. Python's default json.dumps(...) escapes non-ASCII — you'll get a bad_signature 401 the first time you include an em-dash, curly quote, or accented character. Pass ensure_ascii=False.

Links

• https://spoc.com — the underlying service
• https://spoc.com/mcp/manifest — the tool catalogue
• https://spoc.com/docs/api — the full HTTP API

License

MIT