# TokenLab MCP Server

[![CI](https://github.com/hedging8563/tokenlab-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/hedging8563/tokenlab-mcp-server/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/%40tokenlabai%2Fmcp-server)](https://www.npmjs.com/package/@tokenlabai/mcp-server)
[![npm downloads](https://img.shields.io/npm/dm/%40tokenlabai%2Fmcp-server)](https://www.npmjs.com/package/@tokenlabai/mcp-server)

OpenAPI-generated Model Context Protocol server for TokenLab public model discovery, pricing, native LLM endpoints, typed decisions, multimodal generation, async tasks, files, embeddings, rerank, translation, resources, prompts, and the broader developer API.

It exposes public catalog tools for agents that need to choose models, inspect supported request formats, or compare pricing before calling TokenLab APIs. Credentialed tools cover text inference, image generation and editing, video, music, 3D, async task polling, embeddings, rerank, typed decisions, and text translation.

## Generated Tool Profiles

The checked-in `generated/tools.json` manifest is generated from TokenLab's public OpenAPI document plus the small MCP-only overlay in `contract/mcp-overlay.json`. Version 0.6.30 generates 87 endpoint tools; with the two MCP-only composite discovery tools, the full profile returns 89 tools from `tools/list`.

| Profile | Endpoint tools | Total registered tools | Model-facing schema | Coverage |
| --- | ---: | ---: | --- | --- |
| `catalog` | 4 | 6 | Exact | Public model discovery and pricing only; no API key required |
| `core` (default) | 30 | 32 | Portable | Catalog and pricing; Chat Completions, Responses, Anthropic Messages, Gemini generateContent; System One typed decisions; images, video, music, 3D, speech and transcription; async tasks; files; embeddings, rerank, and translation |
| `full` | 87 | 89 | Portable | Every allowlisted developer API operation in the checked-in OpenAPI snapshot, including core plus response lifecycle, batches, worlds, and native model discovery |

The total registered count is the number returned by `tools/list`. All profiles include `compare_models` and `get_api_overview`, producing totals of 6, 32, and 89 tools. Realtime and streaming-only operations are excluded because stdio MCP tool calls return one final result. API operations that accept `stream` fix it internally to `false` without exposing a boolean `const` to provider adapters, and the Gemini query-string API key is intentionally hidden from tool arguments. `create_gemini_content` exposes the camelCase Gemini fields (`systemInstruction`, `generationConfig`, `safetySettings`, `toolConfig`, `cachedContent`) and hides their snake_case proto spellings, which the API accepts as aliases.

The portable projection keeps every top-level argument but bounds deeply nested model-facing shapes. The server still validates calls against the complete generated OpenAPI schema before issuing an API request. Compatibility budgets keep `core` at no more than 60 KB and depth 8, and `full` at no more than 115 KB and depth 8 for the complete `tools/list` response. Tests also run the full profile through the Google AI SDK version used by the observed OpenCode/Gemini failure and keep its function declarations within 90 KB.

Set `TOKENLAB_MCP_TOOL_PROFILE=catalog` for the smallest public-only tool list or `TOKENLAB_MCP_TOOL_PROFILE=full` for the broad developer API. Set `TOKENLAB_MCP_SCHEMA_MODE=exact` only when a client needs the complete nested JSON Schema and can accept its larger/deeper tool payload. Use `strict` for providers that require every property to be listed in `required` and every object to set `additionalProperties: false`; complex top-level arguments are represented as JSON-encoded strings and decoded before canonical validation. Canonical tool names, descriptions, input JSON Schemas, HTTP bindings, content types, auth requirements, and task behavior can be inspected in [`generated/tools.json`](./generated/tools.json).

The smaller [`generated/public-contract.json`](./generated/public-contract.json) is the machine-readable projection used by TokenLab's website and other public consumers. It contains package identity, profile counts, core tool layers, resources, prompts, and source hashes without copying all endpoint schemas.

## Native MCP Features

- JSON tool responses include `structuredContent` while retaining serialized text for older clients.
- HTTP errors retain the original response text (up to 4,000 characters), including public correction hints, alongside structured status, request ID and retry timing. Only the request ID and retry headers are exposed; failed generation requests are never submitted again automatically.
- Generated tools expose human-readable titles, standard read-only/destructive/idempotent/open-world annotations, and response request IDs when available.
- Tool schemas are published and validated directly as JSON Schema. The runtime does not round-trip generated tool schemas through Zod; `exact` mode is byte-shape equivalent to the generated canonical schema.
- Three resources expose the live API overview, the package's OpenAPI snapshot, and the compact MCP public contract.
- `choose_tokenlab_model` and `build_tokenlab_request` prompts guide agents to use live model truth and preserve native endpoint shapes.
- Server instructions tell clients to confirm billable or destructive operations and treat external model/API output as untrusted content.

## Run

```bash
npm install
npm start
```

Install from npm:

```bash
npx -y @tokenlabai/mcp-server
```

Agent-assisted installers can follow [`llms-install.md`](./llms-install.md) for a credential-safe setup and verification flow.

Run in Docker:

```bash
docker build -t tokenlab-mcp-server .
docker run --rm -i tokenlab-mcp-server
```

Add `-e TOKENLAB_API_KEY` when using credentialed API tools. Public catalog tools do not require a key.

Claude Desktop style config:

```json
{
  "mcpServers": {
    "tokenlab-model-catalog": {
      "command": "npx",
      "args": ["-y", "@tokenlabai/mcp-server"],
      "env": {
        "TOKENLAB_API_BASE": "https://api.tokenlab.sh"
      }
    }
  }
}
```

No TokenLab API key is required for public catalog and pricing operations. Set `TOKENLAB_API_KEY` when credentialed tools should call TokenLab APIs. Generated tools preserve the OpenAPI request shape for OpenAI-compatible and native endpoints instead of flattening them into a shared prompt format.

Multipart operations accept local file paths. Small image and audio responses are returned as native MCP content; larger or other binary responses are written to `TOKENLAB_ARTIFACT_DIR` and returned as a path with MIME type and byte count.

## Sync and Async Media Results

Video, music, and 3D creation tools always return an async task. Image generation and editing may return a completed result or an async task depending on the selected model and request.

Media tools preserve the complete TokenLab API response under `response` and add a normalized `delivery` summary:

```json
{
  "delivery": {
    "mode": "async",
    "task_id": "ldtask_...",
    "status": "pending",
    "poll_url": "/v1/tasks/ldtask_...",
    "terminal": false,
    "next_tool": "get_task_status"
  },
  "response": {}
}
```

Use `delivery.mode` instead of assuming all image requests are synchronous. For async tasks, call `get_task_status` with `{ "id": delivery.task_id }` until `delivery.terminal` is `true`. Completion is determined from `status`, not from an optional progress field.

## Environment

- `TOKENLAB_API_BASE`: optional, defaults to `https://api.tokenlab.sh`
- `TOKENLAB_API_KEY`: optional; required for text inference, multimodal generation, async task, embedding, rerank, decision, and translation tools
- `TOKENLAB_MCP_TOOL_PROFILE`: optional, `catalog`, `core` (default), or `full`
- `TOKENLAB_MCP_SCHEMA_MODE`: optional, `portable`, `exact`, or `strict`; defaults to the selected profile's tested mode
- `TOKENLAB_REQUEST_TIMEOUT_MS`: optional request timeout in milliseconds, defaults to `120000`
- `TOKENLAB_MCP_MAX_FILE_BYTES`: optional maximum local upload size per file, defaults to `104857600` (100 MiB)
- `TOKENLAB_MCP_INLINE_BYTES`: optional maximum binary/JSON response size returned inline, defaults to `2097152` (2 MiB)
- `TOKENLAB_ARTIFACT_DIR`: optional output directory for non-inline response artifacts, defaults to the OS temp directory under `tokenlab-mcp`

For Chat Completions image inputs, prefer byte-accurate data URLs such as `data:image/png;base64,...`. If an MCP caller labels a recognized PNG, JPEG, WebP, or GIF payload as `application/octet-stream`, the server corrects that generic MIME before forwarding. An unrecognized generic binary payload is rejected locally with a precise input error.

## Contract Sync

The public OpenAPI document is the API contract source. The overlay contains only MCP-specific choices: profile exposure, stable tool aliases, secret omission, non-streaming constraints, content-type variants, async task semantics, and the compact public projection consumed by the website and docs gates.

```bash
npm run contract:source-check # compare the snapshot with the live canonical OpenAPI (read-only)
npm run contract:check        # check generated output against the checked-in snapshot (offline)
npm run contract:sync         # fetch OpenAPI and regenerate; refuses dirty outputs or a stale branch
npm test                      # compile profiles and test exact/portable/strict schemas, provider conversion, routing, tasks, files, and binary output
```

Always run `git pull --ff-only` before a manual contract sync. `contract:check` proves internal consistency only; `contract:source-check` proves freshness against the canonical source. The scheduled `Sync TokenLab OpenAPI contract` workflow runs the full write sequence and commits only the verified OpenAPI snapshot and generated manifest to `main`. A failed fetch, stale local branch, dirty generated output, generation error, schema compilation error, or test leaves the tracked contract unchanged.

## MCP Registry Metadata

This repository includes `server.json` for the official MCP Registry.

Release metadata:

- npm package: `@tokenlabai/mcp-server@0.6.30`
- MCP registry name: `io.github.hedging8563/tokenlab`
- `package.json.mcpName`: `io.github.hedging8563/tokenlab`

For a new release:

1. Bump the matching versions in `package.json`, `package-lock.json`, and `server.json`.
2. Push a matching tag such as `v0.6.0`.
3. The publish workflow tests and publishes npm through trusted publishing, then publishes the MCP Registry entry through GitHub Actions OIDC.

The same workflow can be run manually from `main` to republish only the current MCP Registry metadata. No npm or MCP Registry token is stored in GitHub.

## Security

Use the `catalog` profile when no credentialed tools are needed. Keep `TOKENLAB_API_KEY` in the local MCP client's secret environment, enable human confirmation for billable and destructive calls, and review tool annotations before granting persistent approval. Do not send a TokenLab API key to an untrusted hosted MCP server.

## Links

- Website: https://tokenlab.sh/mcp
- Docs: https://tokenlab.sh/docs
- OpenAPI: https://tokenlab.sh/docs/openapi.json
- Model catalog: https://api.tokenlab.sh/v1/models
- Skills: https://github.com/hedging8563/tokenlab-skills

## Webhook management

Use the `full` profile to configure workspace webhooks with `list_webhooks`, `create_webhook`, `get_webhook`, `update_webhook`, `delete_webhook`, `rotate_webhook_secret`, `test_webhook` and `list_webhook_deliveries`.

Set `TOKENLAB_MANAGEMENT_TOKEN=mt-...` separately from `TOKENLAB_API_KEY=sk-...`. Create the management token at [Dashboard → API → Management Tokens](https://tokenlab.sh/dashboard/api?tab=tokens). It authorizes management operations only within its workspace and is not limited to webhooks. The inference key cannot substitute for it; the `whsec_...` returned by creation/rotation is for receiver signature verification only. Keep all credentials out of tool arguments and prompts.

Webhook notifications avoid continuous task polling. On a polling fallback, stop on terminal status, 401/403/404 or `retryable: false`; back off on transient failures. See the [complete webhook guide](https://tokenlab.sh/docs/en/guides/webhooks) for payloads, signing, deduplication and delivery history.