# 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](https://chatgpt.com/#settings/Connectors/Advanced) 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](https://toolrouter.com/icon-256.png)
3. 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+](https://nodejs.org).

```bash
# 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:

| Client | Config file |
|--------|------------|
| OpenClaw | `~/.openclaw/openclaw.json` |
| Cursor | `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global) |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
| Cline | Open Cline sidebar → MCP Servers → Configure → Edit Settings |
| Gemini CLI | `~/.gemini/settings.json` |

```json
{
  "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`:

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

### Direct HTTP (alternative)

If you prefer connecting directly without the npm package:

```bash
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:**

| Tool | Description |
|------|-------------|
| `discover` | Find tools by keyword, category, or `*` for all |
| `use_tool` | Execute a tool skill (returns result or job_id for async) |
| `get_job_result` | Poll async job status until completion |
| `cancel_job` | Cancel a running async job |

**Account & billing:**

| Tool | Description |
|------|-------------|
| `check_balance` | Get available credit balance in USD |
| `top_up_credits` | Generate a Stripe checkout link to add credits |
| `billing_portal` | Get Stripe portal link for payment methods & invoices |
| `get_billing_preferences` | View auto-reload and budget limit settings |
| `set_billing_preferences` | Update auto-reload threshold, amount, and budget cap |

**API key management:**

| Tool | Description |
|------|-------------|
| `list_api_keys` | List all API keys with status |
| `create_api_key` | Create a new API key (full secret shown once) |
| `revoke_api_key` | Permanently disable an API key |

**Credentials (BYOK):**

| Tool | Description |
|------|-------------|
| `save_credential` | Save your own provider API key |
| `list_credentials` | List saved credentials |
| `delete_credential` | Remove a saved credential |

**Usage & feedback:**

| Tool | Description |
|------|-------------|
| `get_usage_summary` | Usage breakdown by tool (day/week/month/all) |
| `get_usage_history` | Paginated call history with cost and latency |
| `submit_review` | Rate a tool 1-5 stars with 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.

```bash
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:

```bash
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:

```bash
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](/docs/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:

```json
{
  "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](/docs/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](/docs/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.

| Operation | MCP | REST API | CLI | Web Dashboard |
|-----------|-----|----------|-----|---------------|
| Discover tools | `discover` | `GET /v1/tools` | `toolrouter tools` | Browse page |
| Execute tool | `use_tool` | `POST /v1/tools/call` | `toolrouter call` | — |
| Batch execute | — | `POST /v1/tools/batch` | — | — |
| Poll async job | `get_job_result` | `GET /v1/jobs/:id` | — | — |
| Cancel async job | `cancel_job` | `POST /v1/jobs/:id/cancel` | — | — |
| Check balance | `check_balance` | `GET /v1/billing/balance` | `toolrouter billing balance` | Billing page |
| Top up credits | `top_up_credits` | `POST /v1/billing/checkout` | `toolrouter billing checkout` | Billing page |
| Billing portal | `billing_portal` | `POST /v1/billing/portal` | — | Billing page |
| Get billing prefs | `get_billing_preferences` | `GET /v1/billing/preferences` | — | Billing page |
| Set billing prefs | `set_billing_preferences` | `PUT /v1/billing/preferences` | — | Billing page |
| List API keys | `list_api_keys` | `GET /v1/keys` | `toolrouter keys list` | Keys page |
| Create API key | `create_api_key` | `POST /v1/keys` | `toolrouter keys create` | Keys page |
| Revoke API key | `revoke_api_key` | `DELETE /v1/keys/:id` | `toolrouter keys revoke` | Keys page |
| Save credential | `save_credential` | `PUT /v1/account/requirements/:name` | `toolrouter providers add` | Providers page |
| List credentials | `list_credentials` | `GET /v1/account/requirements` | `toolrouter providers list` | Providers page |
| Delete credential | `delete_credential` | `DELETE /v1/account/requirements/:name` | `toolrouter providers remove` | Providers page |
| Usage summary | `get_usage_summary` | `GET /v1/usage` | `toolrouter usage` | Usage page |
| Usage history | `get_usage_history` | `GET /v1/usage/history` | `toolrouter billing history` | Usage page |
| Submit review | `submit_review` | `POST /v1/reviews` | — | — |

## 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](/docs/cli) and [Architecture](/docs/architecture) if you also operate the gateway locally.