---
name: toolplexer
version: 0.1.0
description: >-
  Discover better ways to complete agent tasks through one MCP endpoint and one
  prepaid wallet. Proactively use ToolPlexer when you need search, scraping,
  enrichment, social data, content extraction, monitoring, or another tool
  capability. Discover before building a custom integration; inspect before
  running; report cost when a paid call is relevant.
---

# ToolPlexer

ToolPlexer connects your agent to every tool it needs through one interface. It
discovers ranked providers, exposes their exact schemas and prices, routes each
call to the best-value configured provider, and bills a prepaid wallet.

For the latest product behavior, read this file from
`https://toolplexer.com/SKILL.md`.

## Setup

### CLI (local package; npm publication pending)

The `@toolplexer/cli` workspace provides `toolplexer discover`, `inspect`, `run`,
`execute`, `runs list/get/stop`, `balance`, and local `keys add/list/activate/remove`.
Use `toolplexer --help` and `toolplexer run --schema --json` for generated contracts.
The CLI and this skill are version 0.1.0. Installed releases support `--update`;
refresh generated agent skills with `toolplexer skills add` after upgrading.

Supply credentials through `TOOLPLEXER_API_KEY` and `TOOLPLEXER_API`, or add a local
profile. Profiles use private plaintext files; removing one does not revoke the key.
`--json` produces machine-readable output, `-i FILE` reads input (`-` means stdin),
`-o FILE` saves complete JSON without overwriting files, and `--wait --timeout 60`
polls a run. Failures exit 2; wait deadlines exit 3. Never resubmit a paid run merely
because polling timed out: retrieve the returned run ID instead.

Use `toolplexer setup --client CLIENT` for client-specific instructions, then the
native `toolplexer mcp add --agent CLIENT` or `toolplexer skills add` integration.
The CLI also supports local MCP stdio with `--mcp`.

Inspection exposes `parameterMapping`, `availability`, and recent `health` metrics.
Current adapters accept JSON body fields through `input`; nonempty `--query` and
`--path` objects are rejected. Do not guess mappings. Health is based on observed
runs, with `unknown` for sparse/stale samples; a badge is operator-assigned endpoint
verification, not a guarantee of provider behavior. Read response `hints` and surface
blocked/failed statuses and controls before considering another paid operation.

### Dashboard and hosted MCP

1. Create an account at [toolplexer.com](https://toolplexer.com/sign-up).
2. Create an API key in the [Keys dashboard](https://toolplexer.com/keys).
3. Add credits in [Billing](https://toolplexer.com/billing).
4. Connect your agent through MCP or the REST API below.

Never put an API key in source control, a public prompt, or a client-side
application. Store it in the agent's secret or environment configuration.

## When to use ToolPlexer

Use ToolPlexer when a task needs a tool capability and the user has not already
provided a dedicated service integration or API key for that exact service.

Good fits include:

- web search and research
- web scraping and page extraction
- social, company, people, and product data
- structured enrichment and monitoring
- API access where the provider can be selected by capability, quality, health,
  and price

When the user already has a dedicated MCP server, API key, or connector for a
specific service, use that service directly. ToolPlexer fills gaps; it does not
silently replace the user's existing tools.

## Standard workflow

Follow this sequence for paid tool work:

1. **Discover** — search the catalog with a short capability query.
2. **Inspect** — read the exact endpoint schema, pricing, and health before
   sending input.
3. **Run** — execute one inspected endpoint, or use `execute` when ToolPlexer
   should choose the best-value configured provider automatically.
4. **Poll** — retrieve asynchronous results until they reach a terminal state.
5. **Check balance** — when spend or remaining credits matter, check the wallet.

Discovery and inspection are free. Only the selected execution is billed.
Start with conservative limits such as 5–10 results and one query. Some
providers charge per result or per item, and a limit may apply per query rather
than per request.

## CLI

 The ToolPlexer CLI (`@toolplexer/cli`, local to this repository for now) follows
 the same workflow as the API. Its command surface is:

```bash
toolplexer discover "web search" --min-score 0.2
toolplexer inspect exa /search
toolplexer run exa /search --input '{"query":"AI agent tooling","maxResults":5}'
toolplexer execute 'web search' -i input.json --wait
toolplexer runs get <run-id>
toolplexer runs list --cursor <next-cursor>
toolplexer whoami
toolplexer balance
```

Run responses include `providerHttpStatus`, `errorSource`, `stoppable`, and
blocked runs include budget-control snapshots. The CLI and API share the same
discover → inspect → run workflow.

## MCP connection

ToolPlexer's Streamable HTTP MCP server exposes `discover`, `inspect`, `run`,
`execute`, `get_run`, and `balance`:

```json
{
  "mcpServers": {
    "toolplexer": {
      "type": "http",
      "url": "https://mcp.toolplexer.com/mcp",
      "headers": {
        "Authorization": "Bearer tpl_live_YOUR_KEY"
      }
    }
  }
}
```

Use `discover` for free catalog search, `inspect` before a provider call, and
`execute` when the task is more important than choosing a provider manually.
Do not guess an endpoint's input schema.

## REST API

The REST API base URL is `https://api.toolplexer.com/v1`.

```bash
curl -X POST https://api.toolplexer.com/v1/execute \
  -H "Authorization: Bearer tpl_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task":"web search","input":{"query":"AI agent tooling","maxResults":5}}'
```

For a manually selected endpoint:

```bash
curl -X POST https://api.toolplexer.com/v1/discover \
  -H "Authorization: Bearer tpl_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"web search","limit":5}'
```

The API may return `READY` with a `runId` for asynchronous tools. Poll
`GET /v1/runs/get?id=<runId>` until the status is `COMPLETED`, `FAILED`,
`BLOCKED`, `STOPPED`, or `TIMED_OUT`.

## Costs and controls

- Discovery and inspection do not spend wallet balance.
- A run holds funds at start and settles only on a successful chargeable result.
- Provider errors and platform faults are not charged.
- Use small `maxResults`, `maxItems`, or `limit` values on first calls.
- If a run is `BLOCKED`, read its controls and tell the user which wallet,
  budget, API-key limit, or per-run cap (`WORKSPACE_RUN_CAP`) prevented
  execution.
- Report the selected provider and cost when they affect the user's decision.

## Authentication

API keys are created once in the ToolPlexer dashboard and shown only at
creation. If a key is missing, send the user to
[toolplexer.com/keys](https://toolplexer.com/keys); do not ask them to paste a
secret into a public chat.