Integration

ToolRouter is intentionally exposed through two machine-facing protocols: MCP for agent clients and REST for direct HTTP integrations.

Base endpoints#

• Website: https://toolrouter.com
• Hosted API: https://api.toolrouter.com
• MCP endpoint: https://api.toolrouter.com/mcp
• Local HTTP gateway: http://localhost:3141

How do I integrate via MCP?#

MCP (Model Context Protocol) is the standard way AI agents discover and call tools. ToolRouter exposes its full catalog as MCP tools. No API key needed — your account is created automatically on first use.

Claude (recommended — easiest setup)#

Add ToolRouter as a connector in any Claude app. Go to Settings → Connectors → Add custom connector and enter:

• Name: ToolRouter
• URL: https://api.toolrouter.com/mcp

Click Add. Works immediately on Claude web, desktop, phone, and Claude Code.

ChatGPT#

ChatGPT requires Developer mode to add custom MCP servers:

1. Go to Settings → Apps → Advanced settings and enable Developer mode
2. Tap Create app and fill in:

• Name: ToolRouter
• MCP Server URL: https://api.toolrouter.com/mcp
• Icon (optional): download from toolrouter.com/icon-256.png

1. Check the acknowledgement box and tap Create

npm package (terminal agents and editors)#

The toolrouter-mcp npm package bridges stdio to the hosted API. Requires Node.js 18+.

# Claude Code
claude mcp add toolrouter -- npx -y toolrouter-mcp

# Codex CLI
codex mcp add toolrouter -- npx -y toolrouter-mcp

For other agents, add to the appropriate MCP config file:

{
  "mcpServers": {
    "toolrouter": {
      "command": "npx",
      "args": ["-y", "toolrouter-mcp"]
    }
  }
}

If you already have other MCP servers configured, add the "toolrouter" entry inside your existing "mcpServers" object — don't replace the whole file.

VS Code (Copilot) uses a different format — add to .vscode/mcp.json:

{
  "servers": {
    "toolrouter": {
      "command": "npx",
      "args": ["-y", "toolrouter-mcp"]
    }
  }
}

Direct HTTP (alternative)#

If you prefer connecting directly without the npm package:

claude mcp add toolrouter \
  --url https://api.toolrouter.com/mcp \
  --header "Authorization: Bearer <YOUR_API_KEY>"

Runtime behavior#

• POST /mcp is the supported stateless entrypoint
• discovery through tools/list stays open (no auth required)
• hosted deployments require auth on tools/call
• image-producing skills can return inline image content and download URLs

MCP meta-tools#

When connected via MCP, agents get 18 meta-tools that cover the full platform — tool discovery, execution, account management, billing, and usage tracking.

Tool discovery & execution:

Account & billing:

API key management:

Credentials (BYOK):

Usage & feedback:

How do I discover tools via REST?#

Send GET /v1/tools to list all tools, GET /v1/tools/search?q=seo to search by keyword, or GET /v1/tools/:tool for a single tool's full details including skills, schemas, and examples. No authentication required for discovery endpoints.

Use the REST API when you want explicit HTTP control or a non-MCP environment.

curl https://api.toolrouter.com/v1/tools
curl "https://api.toolrouter.com/v1/tools/search?q=seo"
curl https://api.toolrouter.com/v1/tools/seo

The gateway exposes these endpoints:

Discovery (no auth):

• GET /health — server status
• GET /v1/tools — list all tools
• GET /v1/tools/search?q=... — search tools by keyword
• GET /v1/tools/:tool — single tool detail
• GET /v1/tools/:tool/backends — which providers serve a tool
• GET /v1/tools/mcp — tools in MCP format
• GET /v1/providers — list all providers
• GET /v1/providers/:slug — provider detail with tools powered
• GET /v1/assets/:assetId — download a tool-produced file

Execution (auth required):

• POST /v1/tools/call — execute a tool skill (supports dry_run and stream)
• POST /v1/tools/batch — run up to 10 calls concurrently

Async jobs (auth required):

• GET /v1/jobs/:jobId — get async job status and result
• POST /v1/jobs/:jobId/cancel — cancel a running async job

Billing (auth required):

• GET /v1/billing/balance — current credit balance
• POST /v1/billing/checkout — create a Stripe invoice to purchase credits
• POST /v1/billing/portal — get Stripe billing portal URL
• GET /v1/billing/preferences — get auto-reload and budget settings
• PUT /v1/billing/preferences — update auto-reload and budget settings
• POST /v1/billing/webhook — Stripe webhook receiver (internal)

Keys (auth required):

• POST /v1/keys — create API key
• GET /v1/keys — list keys
• GET /v1/keys/:id — key details
• DELETE /v1/keys/:id — revoke key

Credentials / BYOK (auth required):

• GET /v1/account/requirements — list saved provider keys
• PUT /v1/account/requirements/:name — save/update a provider key
• DELETE /v1/account/requirements/:name — remove a provider key

Usage (auth required):

• GET /v1/usage — usage summary by tool/skill
• GET /v1/usage/history — recent call history with costs

Reviews (auth required):

• POST /v1/reviews — submit a tool review (1-5 stars + text)

How does authentication work?#

Hosted tool execution requires a Bearer token in the Authorization header. The same API key works for REST tool execution, key management, usage endpoints, and hosted MCP tools/call. Keys follow the tr_live_* format.

Hosted tool execution requires a Bearer token:

Authorization: Bearer <YOUR_API_KEY>

The same header works for:

• REST tool execution
• key management endpoints
• usage endpoints
• hosted MCP tools/call

How do I use my own provider keys (BYOK)?#

Pass upstream API keys via normalized headers like X-Provider-Key-OpenAI: sk-.... The gateway makes them available to skill handlers for that single request. When BYOK headers are present, billing drops to a 5% platform fee instead of the full markup.

ToolRouter forwards upstream provider keys in a normalized header format:

X-Provider-Key-OpenAI: sk-...
X-Provider-Key-Anthropic: sk-ant-...
X-Provider-Key-Serper: sp-...

The gateway normalizes those headers into a provider-to-key map and makes them available to skill handlers. This lets callers override stored credentials for a single request. When BYOK headers are present, the call is billed at a reduced 5% platform fee rather than the full markup — see Billing for details.

How does backend routing work?#

Add a backend field to your /v1/tools/call request to control provider selection. Use order for preferred sequence, only to restrict providers, ignore to exclude them, or sort to rank by price, latency, or throughput. Default routing uses automatic failover.

Tools can be served by multiple upstream providers. You can control which provider handles a call by adding a backend field to your /v1/tools/call request:

{
  "tool": "voice-generator",
  "skill": "generate_voice",
  "input": { "text": "Hello world" },
  "backend": {
    "order": ["elevenlabs", "openai"],
    "allow_fallbacks": true
  }
}

The backend object supports order (preferred provider sequence), only (restrict to specific providers), ignore (exclude providers), sort (rank by price, latency, or throughput), and allow_fallbacks (whether to try the next provider on failure, default true).

If omitted, the gateway uses its default routing logic with automatic failover. See Providers for the full routing model.

How does asset delivery work?#

Skills that produce files (screenshots, exports, images) return output keys ending in _path. The gateway automatically uploads these to the asset store, adds *_url and *_asset to the response, and serves them via GET /v1/assets/:assetId. MCP clients receive small images inline as base64.

Some skills produce files such as screenshots, exports, and transformed images. ToolRouter post-processes output keys that end in _path:

• the file is uploaded to the configured asset store
• the response gets matching *_url and *_asset entries
• local development serves assets from GET /v1/assets/:assetId
• MCP clients can receive small images inline as base64 content

What are the rate limits?#

Default limits per API key are 60 requests per minute, 1,000 per hour, and 5 concurrent. The gateway returns X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers on every response.

The gateway exposes standard rate-limit headers on HTTP responses:

• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset

Every successful or failed call also returns structured usage metadata in the body, including:

• cost — credits debited for this call
• currency — always USD
• credits_remaining — balance after the call
• raw_cost — underlying API cost before markup
• markup — multiplier applied (1.05 for standard, 0.05 for BYOK)

See Billing for the full pricing model including purchase fees and BYOK rates.

How do errors work?#

All errors return a structured ToolRouterError with code, message, type, resolution_hint, and optional retry_after. Error types include auth, billing, rate_limit, validation, provider, and not_found, letting agents branch on stable error categories.

Structured errors follow the ToolRouterError shape and include:

• code
• message
• type
• resolution_hint
• optional retry_after

That allows agents and backends to branch on stable error types such as auth, billing, rate_limit, validation, provider, and not_found.

What can I do from each interface?#

Every account management operation is available from at least MCP, REST, and one other surface. Agents can fully manage a user's account without the user needing to visit the dashboard.

What's the recommended integration pattern?#

Start with GET /v1/tools to inspect the catalog. Resolve the exact tool and skill before generating input. If the tool declares credentials, store them in CLI config or pass provider-key headers. Test with one CLI or REST call before wiring full MCP automation.

1. Start with GET /v1/tools so the caller can inspect the catalog.
2. Resolve the exact tool and skill before generating input.
3. If the tool declares credentials, either store them in CLI config or pass provider-key headers.
4. Prefer one successful CLI or REST call before wiring full MCP automation.
5. Read CLI and Architecture if you also operate the gateway locally.