@octo-dock/mcp-bridge

Stdio ↔ HTTP bridge for OctoDock MCP.

OctoDock serves Model Context Protocol over HTTP at https://octo-dock.com/mcp/{apiKey}. Some MCP clients (e.g. Claude Desktop free tier) only support stdio transport and cannot connect to HTTP remotes directly. This package is a thin bridge: it reads/writes stdio on one side and forwards JSON-RPC messages to the OctoDock HTTP endpoint on the other.

What's new in 0.2.0

OAuth 2.0 + PKCE S256 is now the default login flow. The bridge no longer stores your MCP URL with embedded API key — instead it holds short-lived access tokens + refresh tokens that are auto-rotated. Credential leakage risk drops dramatically (sharing your URL no longer equals sharing your Gmail control).

• Default login opens a browser to OctoDock's authorization page, you click Allow, bridge stores access_token + refresh_token + client_credentials locally (~/.octodock/config.json with chmod 0o600).
• login --legacy-api-key flag keeps the old URL-paste flow for backward compatibility (0.1.x config migrates automatically — no re-login required if you don't want).
• Existing 0.1.x users upgrading to 0.2.0: bridge detects legacy config and keeps working. Run login (without flag) whenever you want to migrate to OAuth.

Quick start

New user (OAuth — recommended)

npx -y @octo-dock/mcp-bridge login

This opens your browser to OctoDock's authorization page. Sign in, click Allow, bridge saves OAuth credentials to ~/.octodock/config.json.

Existing 0.1.x user or OAuth not available (legacy)

npx -y @octo-dock/mcp-bridge login --legacy-api-key

This opens octo-dock.com/dashboard, you copy your legacy MCP URL (the one containing ak_xxxxxx) from the collapsed section on the dashboard, paste it back into the terminal.

Then add the bridge to your MCP client config.

Claude Desktop

Edit claude_desktop_config.json:

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

{
  "mcpServers": {
    "octodock": {
      "command": "npx",
      "args": ["-y", "@octo-dock/mcp-bridge@latest"]
    }
  }
}

Restart Claude Desktop.

Any other stdio MCP client

Run npx -y @octo-dock/mcp-bridge with no args. It reads ~/.octodock/config.json and starts forwarding stdio ↔ HTTP.

Environment variables

• OCTODOCK_MCP_URL — override the stored URL at runtime, legacy mode only (useful in CI / Docker).
• OCTODOCK_DASHBOARD_URL — override the dashboard URL opened by legacy login --legacy-api-key (default https://octo-dock.com/dashboard).
• OCTODOCK_ISSUER_URL — override OAuth issuer base URL used by default login (default https://octo-dock.com).

How it works

The bridge opens two MCP SDK transports and wires their onmessage / send hooks together:

• StdioServerTransport — reads the MCP client's JSON-RPC messages on stdin, writes responses to stdout.
• StreamableHTTPClientTransport — sends JSON-RPC to OctoDock remote, subscribes to SSE for server-initiated messages.
  • OAuth mode (0.2.0+ default): connects to https://octo-dock.com/mcp with Authorization: Bearer <access_token>. Access tokens auto-refresh before expiry (60-second window); if refresh fails, bridge shuts down and asks you to re-login.
  • Legacy mode: connects to https://octo-dock.com/mcp/{apiKey} directly (API key in URL).

No message parsing or state machine — pure forwarding. Whatever your MCP client says, OctoDock hears; whatever OctoDock says, your MCP client hears.

Why a dedicated package

You could use the generic mcp-proxy and feed it your URL manually. This package is a drop-in replacement with three improvements:

1. Credential-free config — your MCP URL (which contains your API key) lives in ~/.octodock/config.json with 0600 perms, not in your committed claude_desktop_config.json.
2. First-run setup — login command opens the dashboard for you.
3. Versioning we control — we can upgrade the bridge without asking you to edit Claude Desktop config.

License

BSL-1.1 — see repo root LICENSE.