The 1ToolRing MCP (Model Context Protocol) server exposes the catalog as tools over streamable HTTP: thousands of third-party tools across SERP, scraping, enrichment, social, ecommerce and maps, plus the native services. An agent discovers a tool by job, inspects its input and price, runs it, and gets back the answer plus the charge. It never needs to know a path or a parameter name in advance.

Endpoint: `https://mcp.1toolring.com/mcp`

Auth: `Authorization: Bearer <key>`, your own 1ToolRing key, sent as an HTTP header on the endpoint. The server accepts Bearer only.

## Tool catalog: discover, inspect, run

| Tool | Arguments | Description |
| --- | --- | --- |
| `discover_tools` | `query`, `limit?` (1 to 20) | Search thousands of tools by job. Returns tool ids, descriptions and the price in credits. Free. |
| `inspect_tool` | `tool` | One tool's `input_schema` (`body`, `queryParams`, `pathParams`), price model and health. Free. |
| `run_tool` | `tool`, `input`, `wait?` (default `true`) | Run the tool with your credits. Credits are held, then settled to the real cost; a failed run costs 0. A slow tool is polled every 3 seconds for about 60 seconds; if it is still running you get its `run_id`. |
| `get_tool_run` | `run_id` | Status and result of a run (`running`, `completed`, `failed`). Free. Only your own runs. |

```text
discover_tools({ query: "find a work email from name and company domain" })
→ { results: [{ id: "<provider>/<endpoint>", description: "...", price: { model: "per_call", credits: ... } }, ...] }

inspect_tool({ tool: "<id from discover>" })
→ { input_schema: { body: { ... } }, price: { model: "per_call", credits: ... }, health: { ... } }

run_tool({ tool: "<id>", input: { body: { first_name: "Ana", last_name: "Putri", domain: "example.com" } } })
→ { run_id: "run_...", status: "completed", credits_charged: ..., output: { ... } }
```

Errors come back as `isError` results with 1ToolRing's own code: `INSUFFICIENT_CREDITS` (with `balance`, `needed` and a `topup_url`), `TOOL_BLOCKED`, `RUN_TOO_LARGE`, `TOOL_NOT_FOUND`, `UPSTREAM_ERROR`, `TOOLS_UNAVAILABLE`. A failed run returns only the short `provider_error`, never the provider's raw response. See [Tools](/reference/tools) for the REST routes and the pricing model.

## Native services

| Tool | Arguments | Description |
| --- | --- | --- |
| `search_catalog` | `query`, `category?`, `capability?`, `limit?` | Search the active catalog by job. Returns entries with `id`, `method`, `path`, `price_credits`, `price_unit`, `capability` and `freshness`. Free. |
| `call_service` | `id`, `query?`, `body?`, `path_params?` | Read the entry by `id`, build the real request, and send it with your key. `query` for GET parameters, `body` for a POST body (including a routed `toolring.<capability>` job), `path_params` for `{placeholders}` in the path. Returns the upstream answer, the status, which source served it, and the charge. |

```text
search_catalog({ query: "verify email" })
→ [{ id: "email.verify", method: "POST", path: "/api/v1/email/verify", price_credits: 105, price_unit: "chargeable address", ... }]

call_service({ id: "email.verify", body: { email: "user@example.com" } })
→ { status: 200, charged: 105, data: { result: "ok", ... } }
```

## Client configuration

```json
{
  "mcpServers": {
    "toolring": {
      "url": "https://mcp.1toolring.com/mcp",
      "headers": { "Authorization": "Bearer aip_live_..." }
    }
  }
}
```

This works in Claude Desktop, Cursor, and any MCP client that supports streamable HTTP with custom headers. The key is forwarded to the API on every call and is never logged or returned.

## Transport

- `POST`, `GET`, `DELETE /mcp`: MCP streamable HTTP, stateless, JSON responses.
- `GET /health`: liveness probe.

## Without MCP

The REST contract is agent-friendly on its own. `GET https://api.1toolring.com/llms.txt` is generated from the same registry the billing path uses and teaches the whole loop in plain text, so an agent that cannot speak MCP can still read the catalog and call it with curl. For the tool catalog the same flow is three REST calls: `POST /api/v1/tools/discover`, `POST /api/v1/tools/inspect`, `POST /api/v1/tools/run` (poll `GET /api/v1/tools/runs/{run_id}` after a `202`).