TokenLab MCP Server

Choose what your agent needsCopy Anchor Link

• MCP adds TokenLab API tools to a compatible client. Start with the key-free catalog setup below.
• The TokenLab Skill installs integration instructions with npx skills add; it does not start an MCP server.

Both extend an existing agent. Changing its main model provider uses that client’s own setup guide.

Let my agent set this upCopy Anchor Link

Copy this task to an agent already running on your computer:

Read this guide and choose MCP catalog tools or a Skill for my task:
https://tokenlab.sh/docs/en/integrations/tokenlab-mcp-server
Check my installed version and active configuration first.
Preserve existing accounts, providers, permissions and other settings.
Back up local files and show proposed changes.
Have me enter any API key locally; never ask for, print or paste it in chat.
Check configuration loading first.
Explain any paid request test separately before running it.

The TokenLab MCP Server lets an MCP client browse current models and prices, send model requests, create media, work with files, and check async tasks.

Use the catalog profile to browse models and prices without an API key. Add TOKENLAB_API_KEY when the client should make paid model or media requests.

RequirementsCopy Anchor Link

Install Node.js 18.17 or newer and make sure npx is available:

node --version
npx --version

The npm package runs locally over stdio. You do not need a global installation or a source checkout.

Choose what the client can useCopy Anchor Link

Start with catalog if you only want better model selection. Use core when the client should create content or call a model. full is for clients that genuinely need the larger tool set.

Add the serverCopy Anchor Link

Back up the active configuration. Add only the TokenLab entry and preserve existing providers, accounts, default-model selection and permissions. If the name is already used, choose another name and update the commands. To undo setup, remove only your added entry or restore its previous backup.

claude mcp add \
  --env TOKENLAB_MCP_TOOL_PROFILE=catalog \
  --scope user \
  tokenlab -- \
  npx -y @tokenlabai/mcp-server@0.6.24

Enable paid toolsCopy Anchor Link

Create an API key in Console → API keys, then set both variables in the MCP server environment:

{
  "env": {
    "TOKENLAB_API_KEY": "<TOKENLAB_API_KEY>",
    "TOKENLAB_MCP_TOOL_PROFILE": "core"
  }
}

Use your client's secret input when it has one. If a real key appears in a shared file, screenshot, log, or shell history, revoke it and create a new key.

Check the connectionCopy Anchor Link

Restart or reload the MCP client, approve the local server if prompted, and confirm that tokenlab is connected.

# Claude Code
claude mcp list

# Codex
codex mcp list

Ask the client to call list_models. A non-empty list confirms the package started and reached TokenLab. The catalog profile does not need an API key.

Useful toolsCopy Anchor Link

Tool availability depends on the selected profile. Common tasks include:

• list models and read one model's capabilities
• read current TokenLab prices or compare several models
• send Chat Completions, Responses, Anthropic Messages, or Gemini requests
• evaluate typed decisions with evaluate_decisions
• create or edit images
• create video, music, 3D, speech, transcription, or translation
• upload and retrieve files
• create embeddings or rerank documents
• check and cancel supported async tasks

The client should ask for approval before a paid call when price or model choice has not already been confirmed.

Decision modelsCopy Anchor Link

Use core or full to call a System One decision model. First call list_models with {"category":"decision"} and get_model with the selected model ID. Keep the agent's main chat model configured separately.

For Jev 1.13, call the tool with native state and questions:

{
  "name": "evaluate_decisions",
  "arguments": {
    "model": "jev-1.13",
    "state": { "ticket": "Please refund the duplicate payment." },
    "questions": {
      "refund_requested": {
        "type": "noul",
        "instructions": "Does the customer explicitly request a refund?"
      }
    }
  }
}

Check isError, then read structuredContent.answers and structuredContent.usage. A Noul answer is a probability number, not a Boolean. Preserve the request ID from _meta when available. The tool returns a synchronous result; it does not use the async task polling flow.

With the default 120,000 ms server request timeout, allow at least 150,000 ms for the client tool call. If you change TOKENLAB_REQUEST_TIMEOUT_MS, keep the client timeout longer. A timeout leaves the outcome uncertain; inspect the request before resubmitting a paid call. Validate decisions against your own labeled cases before using them to drive actions.

Async mediaCopy Anchor Link

Video, music, and 3D tools return a task instead of a finished file. Image tools can return either a completed result or a task, depending on the model.

When a result includes an async delivery, call get_task_status with its task ID until the status is complete or failed. Do not create a second task because one status check timed out.

Optional settingsCopy Anchor Link

Use the defaults unless your client or deployment has a specific requirement.

TroubleshootingCopy Anchor Link

Hosted model explorerCopy Anchor Link

Clients that support Streamable HTTP can use the public model explorer at:

https://tokenlab-model-explorer.vercel.app/mcp

Use the local npm server for paid API calls, local file uploads, or the core and full profiles.

LinksCopy Anchor Link

• TokenLab MCP page
• GitHub repository
• TokenLab API skill
• Model catalog
• API quickstart

Configure task notifications with the Webhook management API, authenticated with an mt-… Management Token. MCP full uses TOKENLAB_MANAGEMENT_TOKEN. Stop polling terminal tasks and on 401/403/404 or non-retryable errors.