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 keeps tools/list compact: agents call discover to search the full catalogue, then use_tool with the selected tool and operation. Discovery is open; execution creates or authenticates an account as needed.

Choose the correct client setup#

Use the agent setup hub for exact current commands and authentication. It covers Claude, Cowork, ChatGPT, Claude Code, Codex, Cursor, Gemini CLI, Grok Build, OpenClaw, Kimi Code, Hermes, Paperclip and Perplexity Computer.

The general remote endpoint is https://api.toolrouter.com/mcp. Claude chat and Cowork guides use the filtered Anthropic profile at /mcp/anthropic. The MCP reference explains discovery and execution; the skill guide explains the separate instruction layer.

For terminal access, use the documented CLI. Client configuration paths and cloud skill visibility differ, so follow the named client's guide rather than copying a generic config across runtimes.

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 initializes or continues a bounded Streamable HTTP session; subsequent requests send MCP-Session-Id
• 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 Apps-capable hosts receive a negotiated ui://toolrouter/app interface with structured-data and text fallbacks
• Skills-aware hosts can progressively load operation guidance through the draft io.modelcontextprotocol/skills extension
• clients that negotiate neither extension retain the ordinary text tool flow

MCP meta-tools#

When connected via MCP, agents receive a compact set of meta-tools for discovery, execution, async jobs, files, billing, credentials, teams, connected MCP servers, and account controls. Start with discover, call catalogue operations through use_tool, and use job_get or job_cancel for asynchronous work. Treat the live tools/list response as authoritative; the set evolves with platform capabilities and connector policy.

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. Reduced BYOK billing applies when the handler actually selects that request credential, or a saved personal/team credential—not merely because an unused header is present.

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 the selected credential belongs to the user or team, 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 for a model that has multiple provider endpoints. Use order for a preferred sequence, only to hard-switch to one or more providers, or ignore to exclude providers. The canonical model never changes.

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": "generate-image",
  "skill": "text_to_image",
  "input": {
    "prompt": "A product photo on a clean studio background",
    "model": "flux-2-pro"
  },
  "backend": {
    "order": ["fal", "prodia"],
    "allow_fallbacks": true
  }
}

The backend object supports order (preferred provider sequence), only (restrict to specific providers), ignore (exclude providers), and allow_fallbacks (try the next provider after an outage, timeout, or rate limit; default true). Validation, authentication, and billing failures do not fall through to another provider.

Provider routing is opt-in per call. If backend is omitted, the skill's existing direct handler and model selection remain unchanged. Call the tool's list_models skill to see which models have multiple providers. A synchronous response uses meta.backend and meta.fallback_used; an asynchronous job_get response reports the same fields under usage.

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.

For caller-provided local files, upload with POST /v1/assets/upload first and pass the returned ast_... file ID to media inputs. Media inputs accept ToolRouter file IDs and hosted HTTP(S) URLs; hosted tools cannot read caller-machine paths like /Users/alex/Desktop/photo.png. See Files and Media for the full contract.

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 tool-call limits per API key are 60 requests per minute, 1,000 per hour, and 5 concurrent. The gateway returns structured RateLimit-Policy and RateLimit fields on tool-call responses, plus RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset for earlier-draft clients. HTTP 429 responses include Retry-After.

Tool-call responses also retain the existing compatibility headers:

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

Public discovery endpoints are not quota-limited. Public asset endpoints expose a separate public-assets rate-limit policy.

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.

The OpenAPI 3.1 specification references the shared typed error schema from documented 4xx, 5xx, and default responses.

How does API versioning and deprecation work?#

REST endpoints use the versioned /v1 path. ToolRouter announces a scheduled deprecation with the RFC 9745 Deprecation header and a migration link. A resource scheduled to stop responding also sends the RFC 8594 Sunset header. See API Versioning and Deprecation for compatibility guarantees and notice periods.

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.