# ToolSocket docs

> ToolSocket is a remote MCP server and REST API that gives AI agents pay-per-call access to 881 live data tools: TikTok, Douyin (抖音), Xiaohongshu (小红书), WeChat Channels & Official Accounts (微信视频号/公众号), Instagram, YouTube, X/Twitter, Reddit, Weibo (微博), Bilibili (B站), Zhihu (知乎), Kuaishou (快手), LinkedIn, DeFi data, web search, weather, GitHub, Wikipedia, arXiv and more. One endpoint, one API key or OAuth sign-in, one prepaid balance.

- MCP endpoint: `https://toolsocket.top/mcp` (Streamable HTTP)
- REST base URL: `https://toolsocket.top`
- Agent skill: `https://toolsocket.top/SKILL.md`
- Tools by platform: `https://toolsocket.top/tools` (Markdown: append `.md`, e.g. `https://toolsocket.top/tools/douyin.md`)
- Console (sign in, API keys, top-up): `https://toolsocket.top/console`

## Authentication

Two options, both spend the same account balance:

- **OAuth 2.1** (recommended for Claude.ai, ChatGPT, Claude Code, Cursor, VS Code): add the MCP URL; the client opens a ToolSocket sign-in page; click **Allow**. No key to copy.
- **API key**: create one in the Console and send `Authorization: Bearer ts_live_…`.

Free tools (open data, DefiLlama) need no auth over REST. Paid tools and the `/mcp` endpoint require a key or token; unauthenticated `/mcp` requests get `401` with a `WWW-Authenticate` header pointing at the OAuth metadata.

## Connect a client

### Claude.ai / Claude Desktop (OAuth)

1. Settings → Connectors → **Add custom connector**.
2. Name `ToolSocket`, URL `https://toolsocket.top/mcp` → Add.
3. Click **Connect**, sign in (Google, GitHub or email), click **Allow**.
4. Enable the connector in a chat and ask, e.g. "What's trending on Douyin right now?"

Custom connectors need a paid Claude plan; on Team/Enterprise an owner may need to add it first.

### ChatGPT (OAuth)

1. Settings → Apps & Connectors → Advanced settings → turn on **Developer mode**.
2. Apps & Connectors → **Create**. MCP server URL `https://toolsocket.top/mcp`, Authentication **OAuth**.
3. Sign in to ToolSocket, click **Allow**, then enable the connector in a chat.

### Claude Code

```bash
# OAuth: add, then run /mcp inside Claude Code and choose Authenticate
claude mcp add --transport http toolsocket https://toolsocket.top/mcp

# or with an API key
export TOOLSOCKET_API_KEY=ts_live_…
claude mcp add --transport http toolsocket https://toolsocket.top/mcp \
  --header "Authorization: Bearer $TOOLSOCKET_API_KEY"
```

### Cursor — `~/.cursor/mcp.json`

```json
{
  "mcpServers": {
    "toolsocket": {
      "url": "https://toolsocket.top/mcp",
      "headers": { "Authorization": "Bearer ts_live_…" }
    }
  }
}
```

Omit `headers` to sign in with OAuth instead.

### VS Code (Copilot) — `.vscode/mcp.json`

```json
{
  "servers": {
    "toolsocket": { "type": "http", "url": "https://toolsocket.top/mcp" }
  }
}
```

### Windsurf — `~/.codeium/windsurf/mcp_config.json`

```json
{
  "mcpServers": {
    "toolsocket": {
      "serverUrl": "https://toolsocket.top/mcp",
      "headers": { "Authorization": "Bearer ts_live_…" }
    }
  }
}
```

### Codex — `~/.codex/config.toml`

```toml
[mcp_servers.toolsocket]
url = "https://toolsocket.top/mcp"
bearer_token_env_var = "TOOLSOCKET_API_KEY"
```

### stdio-only clients (Cline, Zed, older Claude Desktop configs)

```json
{
  "mcpServers": {
    "toolsocket": {
      "command": "npx",
      "args": ["-y", "toolsocket", "mcp"],
      "env": { "TOOLSOCKET_API_KEY": "ts_live_…" }
    }
  }
}
```

Or the generic bridge: `npx -y mcp-remote https://toolsocket.top/mcp --header "Authorization: Bearer ts_live_…"`.

### SKILL.md (Claude Code, Codex, OpenClaw and other agents that read Markdown skills)

Tell the agent: `set up https://toolsocket.top/SKILL.md`. It then calls the REST API with `curl`; nothing to install.

## MCP tools

ToolSocket exposes a handful of meta-tools instead of 881 separate tool definitions, so the agent's context stays small. Workflow: **discover → inspect → run**. Each MCP connection gets a session id (`Mcp-Session-Id`), so one conversation's calls are grouped automatically.

| Tool | Arguments | What it does |
|---|---|---|
| `discover_tools` | `query`, `limit?` | Natural-language search (English or 中文). Returns ranked tools with price and health. |
| `inspect_tool` | `tool` | Full description, input JSON Schema, example input and hints. |
| `run_tool` | `tool`, `input`, `tag?` | Runs the tool; waits up to 30 s, otherwise returns a run id. `tag` labels the run. |
| `get_run` | `run_id` | Status and output of a run. |
| `list_runs` | `status?`, `tag?`, `tool?`, `session_id?`, `limit?`, `cursor?` | Your recent runs, newest first. |
| `stop_run` | `run_id` | Stop a run that is still running. Stopped runs are not charged. |
| `get_balance` | — | Balance and today's spend. |
| `create_topup_link` | `amount_usd?` | One-time Stripe payment link for the user (minimum $5). Without an amount, returns the limits. |
| `send_feedback` | `text`, `run_id?` | Tell the ToolSocket team what worked, what didn't, or what you couldn't find. |

## REST API

| Endpoint | Purpose |
|---|---|
| `GET /v1/discover?q=…` | Search tools |
| `GET /v1/inspect?tool=…` | Tool details and input schema |
| `POST /v1/run` | Run: `{"tool", "input", "wait": seconds, "tag"?, "session"?}` |
| `GET /v1/runs/:id?wait=20` | Poll a run |
| `GET /v1/runs?status=&tag=&tool=&session=` | Run history, newest first; page with `cursor` (outputs kept 7 days) |
| `POST /v1/runs/:id/stop` | Stop a running run (not charged) |
| `GET /v1/session` | New session id; send it as `X-Session-Id` on every call of one task |
| `POST /v1/topup` | Payment link: `{"amount": 5}` → `{"url", "totalUsd", …}`. `GET` returns the limits |
| `POST /v1/feedback` | Feedback: `{"text", "run_id"?}` |
| `GET /v1/tools` | Whole catalog (JSON) |
| `GET /v1/me` | Balance (with key) |

```bash
curl -s "https://toolsocket.top/v1/discover?q=douyin%20hot%20search"

curl -s -X POST https://toolsocket.top/v1/run \
  -H "Authorization: Bearer $TOOLSOCKET_API_KEY" \
  -H "content-type: application/json" \
  -d '{"tool":"douyin#web/fetch_hot_search_result","input":{},"wait":30}'
```

## CLI

Open source, zero dependencies (Node 18+): <https://github.com/satashili/toolsocket>

```bash
npx -y toolsocket login              # paste your ts_live_ key once
npx -y toolsocket discover "tiktok user videos"
npx -y toolsocket run openmeteo#forecast -i city=Tokyo -i days=2
npx -y toolsocket balance
npx -y toolsocket mcp                # stdio MCP bridge
```

## Pricing and limits

- Every tool shows its per-call price. Social-platform data is mostly **$0.0015 per call**; open-data and DefiLlama tools are **free**; web search is $0.001125.
- Prepaid balance via Stripe; each top-up adds $0.50 + 5%. No subscription.
- Vendor errors and timeouts are refunded automatically.
- Daily and per-key spend limits can be set in the Console.
- Rate limits: 60 runs/min per account or key; 30/min per IP without one.

## Errors

| HTTP | Code | Meaning |
|---|---|---|
| 401 | `AUTH_REQUIRED` · `invalid_token` | Paid tool or MCP without a valid key/token. |
| 402 | `INSUFFICIENT_BALANCE` | The `topup` block suggests an amount. Ask the user, then `POST /v1/topup` for a payment link, or top up in the Console. |
| 402 | `DAILY_LIMIT` · `KEY_LIMIT` | A spend limit you set was reached. |
| 422 | `INVALID_INPUT` | Input doesn't match the schema — call inspect. |
| 429 | `RATE_LIMITED` | Slow down; retry after the given seconds. |

## ToolSocket Agent

A hosted research agent for social-media and market data at <https://agent.toolsocket.top>. It uses the same tools, shows every call and its cost, and bills from the same balance.

Support: support@toolsocket.top · Privacy: https://toolsocket.top/privacy · Terms: https://toolsocket.top/terms
