TOOLBRIDGE documentation

Quickstart

1. Create a free account at /signup.
2. In Dashboard → MCP Servers, add your upstream server: a name, a slug (e.g. github), its Streamable HTTP URL, and the credentials it needs.
3. In Dashboard → API Keys, create a key. It starts with tb_live_ and is shown only once.
4. Point your MCP client at https://toolbridge.cloud/v1/gateway/<slug> with the header Authorization: Bearer <your key> (see "Connect your agent").

Want to try an MCP server before signing up? The playground lets you chat with Claude using any public MCP server's tools — free, no account.

Connect your agent

Every registered server gets its own gateway URL: https://toolbridge.cloud/v1/gateway/<slug>. The gateway speaks MCP's Streamable HTTP transport, so any client that supports remote HTTP MCP servers can connect. Replace github with your slug and tb_live_YOUR_KEY with your API key.

Claude Code

claude mcp add --transport http github https://toolbridge.cloud/v1/gateway/github \
  --header "Authorization: Bearer tb_live_YOUR_KEY"

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "github": {
      "url": "https://toolbridge.cloud/v1/gateway/github",
      "headers": { "Authorization": "Bearer tb_live_YOUR_KEY" }
    }
  }
}

Claude Desktop (claude_desktop_config.json, via mcp-remote)

Claude Desktop's config file launches local processes, so use the mcp-remote bridge to reach the gateway:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://toolbridge.cloud/v1/gateway/github",
        "--header", "Authorization:${TOOLBRIDGE_AUTH}"
      ],
      "env": { "TOOLBRIDGE_AUTH": "Bearer tb_live_YOUR_KEY" }
    }
  }
}

Any HTTP client (curl)

curl -s https://toolbridge.cloud/v1/gateway/github \
  -H "Authorization: Bearer $TOOLBRIDGE_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

How the gateway handles MCP traffic

• Requests are JSON-RPC over HTTP POST; responses come back as JSON or as a Server-Sent Events stream, exactly as your upstream sends them.
• The Mcp-Session-Id, MCP-Protocol-Version, and Last-Event-ID headers are forwarded to your upstream, and the upstream's Mcp-Session-Id is returned to your client, so stateful servers work.
• DELETE on the gateway URL is forwarded so clients can end their session. GET (a standalone server-to-client event stream) is not supported and returns 405, which MCP clients handle automatically.
• Your upstream credentials are injected on every request; your agent never sees them.
• Each response carries X-Toolbridge-Upstream-Latency-Ms.

Upstream authentication

Credentials are encrypted at rest (AES-256-GCM) and are never returned by the API. Upstream URLs must be publicly reachable over http(s); private, loopback, and link-local addresses are rejected.

Built-in memory server

Every account includes a built-in MCP server at https://toolbridge.cloud/v1/gateway/_memory — no registration needed. It exposes your persistent memory store as tools, so an agent can remember facts across sessions.

claude mcp add --transport http memory https://toolbridge.cloud/v1/gateway/_memory \
  --header "Authorization: Bearer tb_live_YOUR_KEY"

Namespaces default to default. Limits: keys up to 256 characters, namespaces up to 64 characters, content up to 100 KB, metadata up to 8 KB. The same items are available over the REST API below and in Dashboard → Memory.

REST API

Base URL https://toolbridge.cloud. Request and response bodies are JSON; errors look like {"error":{"code":"…","message":"…"}}.

Agent API keys (Authorization: Bearer tb_live_…) are data-plane credentials: they can call the gateway, the memory endpoints, GET /v1/servers, GET /v1/billing/usage, and GET /v1/auth/me. Creating or revoking keys and creating, editing, or deleting servers requires a dashboard session — use the dashboard, or send the token returned by POST /v1/auth/login as the bearer token. This way a leaked agent key can never mint new keys or redirect a server's stored credentials.

API keys (dashboard session)

MCP servers (writes need a dashboard session)

Slugs are 3–50 characters: lowercase letters, digits, and dashes, starting and ending with a letter or digit. rate_limit_per_min is optional and is capped at your plan's per-minute limit.

Memory

URL-encode keys in paths (for example with encodeURIComponent).

Usage

curl -s https://toolbridge.cloud/v1/memory \
  -H "Authorization: Bearer $TOOLBRIDGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"namespace":"acme","key":"user:42:prefs","content":"Prefers dark mode and concise answers"}'

curl -s "https://toolbridge.cloud/v1/memory/search?namespace=acme&q=dark%20mode" \
  -H "Authorization: Bearer $TOOLBRIDGE_KEY"

Limits and metering

• Metered calls: every tools/call through the gateway (including the built-in memory server) and every memory read or write over the REST API counts as one call. Protocol traffic — initialize, tools/list, notifications, ping — is logged but not counted.
• When the Free plan's monthly allowance is used up, tools/call returns a JSON-RPC error and metered REST calls return HTTP 402 until the next calendar month (UTC). Paid plans are not cut off at their included volume.
• The per-minute limit applies to all authenticated requests; responses include X-RateLimit-Limit and X-RateLimit-Remaining, and a 429 includes Retry-After. Each server can also have its own lower rate_limit_per_min.
• Request bodies are limited to 5 MB.

See pricing on the home page or upgrade in Dashboard → Usage & Billing.

Errors

Playground

The playground lets anyone chat with Claude (on Amazon Bedrock) using the built-in demo tools or the tools of any public Streamable HTTP MCP server URL — no account needed. Each visitor gets 20 messages per day. Every session has a share link at /playground/<id>; anyone with the link can read the transcript, so don't paste secrets. Sign up from the same browser and your sessions are saved to your account.

Support

Questions or problems? Email info@nubri.co.