TokenLab MCP Server

The TokenLab MCP server generates MCP tools from TokenLab’s public OpenAPI contract. MCP-compatible agents can discover models and pricing, call OpenAI-compatible and native LLM endpoints, create multimodal media, upload files, and manage asynchronous tasks. Use it when an agent needs the current TokenLab API contract instead of a manually maintained tool list. The default core profile exposes 29 generated endpoint tools plus two composite discovery tools. The full profile exposes 78 generated endpoint tools plus the same two composite tools. This page is for adding TokenLab as a tool server inside Claude Code, Cursor, VS Code, Codex, Claude Desktop, Cline, Windsurf, or another MCP client. To call TokenLab directly from application code, start with the API quickstart.

Public catalog and pricing tools do not require a TokenLab API key. Set TOKENLAB_API_KEY for credentialed inference, media, audio, file, task, embedding, rerank, and translation operations. Never place an API key in tool arguments.

What It Provides

Live model discovery from https://api.tokenlab.sh/v1/models.
Model detail lookup from /v1/models/{model}.
Pricing lookup from /v1/models/{model}/pricing.
Agent-readable API overview from https://api.tokenlab.sh/llms.txt.
OpenAI-compatible Chat Completions and Responses, Anthropic Messages, and Gemini generateContent without flattening their native request shapes.
Image generation and editing through JSON URLs, TokenLab file IDs, or local multipart files.
Video, music, 3D, speech, transcription, audio translation, embeddings, multimodal embeddings, rerank, and text translation.
Normalized async task summaries for image, video, music, 3D, and world-generation operations.
A daily contract sync that fetches the public OpenAPI document, regenerates tool schemas, runs endpoint and file tests, and updates main only when every check passes.

Quickstart

The fastest safe setup starts with the six public catalog tools. It does not require a TokenLab API key, and you can enable credentialed tools later.

Install in Cursor

Add the public catalog profile to Cursor in one click

Install in VS Code

Add the public catalog profile to your VS Code user configuration

Check the requirements

Install Node.js 18.17 or newer and confirm that npx is available:

node --version
npx --version

You do not need to install the MCP package globally or clone its repository.

Choose an access level

Goal	API key	Profile
Browse models, details, and pricing	Not required	`catalog` (6 tools)
Use common inference, media, file, and task operations	Required for paid calls	`core` (31 tools, default)
Expose every allowlisted developer operation	Required for paid calls	`full` (80 tools)

Create a key in Dashboard → API Keys only if you want the server to make credentialed API calls. Keep the key in the client’s secret environment; never paste it into a prompt or MCP tool argument.

Configure your client

Choose your client below. The public examples explicitly select the catalog profile so every exposed tool works without a key.

Add TokenLab for your user account so it is available across projects:

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

To enable the default core profile, add the server with your API key instead:

claude mcp add --env TOKENLAB_API_KEY=your-tokenlab-api-key --scope user tokenlab-model-catalog -- npx -y @tokenlabai/mcp-server

Use --scope local for only the current project, or --scope project to create a team-shared .mcp.json. Do not commit a real key to a project configuration.

Use the one-click installer above, or save this as ~/.cursor/mcp.json for all projects or .cursor/mcp.json for one project:

{
  "mcpServers": {
    "tokenlab-model-catalog": {
      "command": "npx",
      "args": ["-y", "@tokenlabai/mcp-server"],
      "env": {
        "TOKENLAB_MCP_TOOL_PROFILE": "catalog"
      }
    }
  }
}

Use the one-click installer above, run MCP: Add Server from the Command Palette, or save this as .vscode/mcp.json:

{
  "servers": {
    "tokenlab-model-catalog": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@tokenlabai/mcp-server"],
      "env": {
        "TOKENLAB_MCP_TOOL_PROFILE": "catalog"
      }
    }
  }
}

For a user-wide setup, run MCP: Open User Configuration and add the same server object there.

Add the public catalog profile:

codex mcp add --env TOKENLAB_MCP_TOOL_PROFILE=catalog tokenlab-model-catalog -- npx -y @tokenlabai/mcp-server

To enable the default core profile, add the server with your API key instead:

codex mcp add --env TOKENLAB_API_KEY=your-tokenlab-api-key tokenlab-model-catalog -- npx -y @tokenlabai/mcp-server

Add the server to claude_desktop_config.json:

{
  "mcpServers": {
    "tokenlab-model-catalog": {
      "command": "npx",
      "args": ["-y", "@tokenlabai/mcp-server"],
      "env": {
        "TOKENLAB_MCP_TOOL_PROFILE": "catalog"
      }
    }
  }
}

Cline CLI can install the published stdio server directly:

cline mcp add tokenlab --yes -- npx -y @tokenlabai/mcp-server

For Windsurf, save the standard mcpServers configuration at ~/.codeium/windsurf/mcp_config.json. Other stdio clients use the same server values: command npx, arguments -y and @tokenlabai/mcp-server, and no working directory.

Restart and verify

Restart or reload the MCP client, approve the local server when prompted, and confirm that tokenlab-model-catalog is connected.

# Claude Code: health-check configured servers
claude mcp list

# Codex: list configured servers
codex mcp list

Then ask the agent to call list_models. A non-empty model list proves that the client started the server, completed MCP discovery, and reached TokenLab’s public catalog. No API key is needed for this check.

Configuration Reference

Use these values in any client that supports local stdio MCP servers. Add each argument as a separate item.

Field	Value	Notes
Server name	`tokenlab-model-catalog`	Any unique name works.
Transport	`stdio`	TokenLab MCP runs as a local child process.
Startup command	`npx`	Starts the published npm package.
Arguments	`-y`, then `@tokenlabai/mcp-server`	Use `@tokenlabai/mcp-server@0.6.17` to pin the currently verified release.
Working directory	Leave blank	`npx` does not require a project directory for this package.

For credentialed tools, add the key and select the tool profile in the server’s environment:

{
  "mcpServers": {
    "tokenlab-model-catalog": {
      "command": "npx",
      "args": ["-y", "@tokenlabai/mcp-server"],
      "env": {
        "TOKENLAB_API_KEY": "<TOKENLAB_API_KEY>",
        "TOKENLAB_MCP_TOOL_PROFILE": "core"
      }
    }
  }
}

If a client expects one server object instead of the mcpServers wrapper, copy only the inner object containing command, args, and env. VS Code is the main exception: its configuration uses a top-level servers object.

Environment variable	Default	Purpose
`TOKENLAB_API_BASE`	`https://api.tokenlab.sh`	Override the TokenLab API base URL. Do not add a trailing slash.
`TOKENLAB_API_KEY`	Not set	Required for credentialed inference, media, file, task, embedding, rerank, and translation calls.
`TOKENLAB_MCP_TOOL_PROFILE`	`core`	Select `catalog`, `core`, or `full`.
`TOKENLAB_MCP_SCHEMA_MODE`	Profile default	Select `portable`, `exact`, or `strict`. Keep `portable` unless the client requires another schema shape.
`TOKENLAB_REQUEST_TIMEOUT_MS`	`120000`	Set the API request timeout in milliseconds.
`TOKENLAB_MCP_MAX_FILE_BYTES`	`104857600`	Set the maximum local upload size per file in bytes.
`TOKENLAB_MCP_INLINE_BYTES`	`2097152`	Set the largest binary or JSON result returned inline in bytes.
`TOKENLAB_ARTIFACT_DIR`	OS temporary directory	Choose where larger response artifacts are written.

Never publish screenshots, logs, shell history, or configuration files containing a real API key. Prefer your client’s secret input or environment-variable support, use placeholders in shared examples, and rotate any exposed key.

Install From Source

Use a source checkout only when you want to audit or develop the MCP server. Normal client setup should use the published npm package shown above.

git clone https://github.com/hedging8563/tokenlab-mcp-server.git
cd tokenlab-mcp-server
npm install
npm test
npm start

The core and full profiles publish bounded portable tool schemas by default while the server validates every call against the complete OpenAPI contract. Set TOKENLAB_MCP_SCHEMA_MODE=exact for complete nested schemas, or TOKENLAB_MCP_SCHEMA_MODE=strict for providers that require closed objects and every property in required; strict mode represents complex top-level values as JSON-encoded strings.

Generated Tool Profiles

Profile	Tools exposed	Coverage
`catalog`	6	Four generated public catalog and pricing tools plus `compare_models` and `get_api_overview`. No API key required.
`core` (default)	31	29 generated endpoint tools plus `compare_models` and `get_api_overview`. Covers catalog, pricing, native LLM endpoints, images, video, music, 3D, audio, tasks, files, embeddings, rerank, and translation.
`full`	80	78 generated endpoint tools plus the two composite discovery tools. Adds response lifecycle, batches, worlds, native model discovery, and other allowlisted developer operations.

Tool names, descriptions, input schemas, HTTP methods, paths, content types, auth requirements, and task behavior are generated from the checked-in OpenAPI snapshot. An MCP-only overlay supplies stable tool aliases, profile membership, async task semantics, multipart variants, secret omission, and non-streaming constraints. Version 0.6.0 also returns JSON through MCP structuredContent, publishes three contract resources, and provides two prompt templates for model selection and native request construction. Generated and composite tools include standard risk annotations so compatible clients can apply safer approval policies. Common core tools include:

Family	Representative tools
Catalog and pricing	`list_models`, `get_model`, `get_model_pricing`, `get_pricing`, `compare_models`
Native LLM endpoints	`create_chat_completion`, `create_response`, `create_anthropic_message`, `create_gemini_content`
Images	`create_image`, `create_image_file`, `edit_image`, `edit_image_file`
Video, music, and 3D	`create_video`, `create_music`, `create_3d_model`
Audio	`create_speech`, `transcribe_audio`, `translate_audio`
Embeddings and text	`create_embedding`, `create_multimodal_embedding`, `rerank_documents`, `translate_text`
Files and tasks	`upload_file`, `list_files`, `retrieve_file`, `retrieve_file_content`, `delete_file`, `get_task_status`, `cancel_task`

MCP tool calls return one final result. Streaming-only and realtime operations are excluded, and the server fixes supported stream arguments to false internally without exposing a boolean constant to provider adapters. Small image and audio responses return native MCP content; larger binary responses are written to TOKENLAB_ARTIFACT_DIR and returned with their local path, MIME type, and byte count.

Async Media Results

Video, music, and 3D creation return async task summaries. Image generation and editing can return either a completed result or an async task, depending on the selected model and request. When delivery.mode is async, call get_task_status with { "id": delivery.task_id } until delivery.terminal is true. Determine completion from status; progress is optional and must not be used as the terminal condition.

Recommended Agent Workflow

Call list_models when the user has not named a model.
Use recommended_for for non-chat tasks, such as image, video, music, 3D, TTS, STT, embeddings, rerank, or translation.
Call get_model before building a non-chat request, retrying a failed request, or switching endpoint families.
Call get_model_pricing when model cost affects the user’s choice.
Use compare_models when the choice depends on several candidates.
Call the generated tool that matches the required API contract, or use get_api_overview for a compact map of TokenLab API families.

Native Endpoint Guidance

TokenLab supports OpenAI-compatible routes and native endpoint families. The MCP server helps an agent choose the right route before it writes code:

Family	Common route
OpenAI-compatible chat	`/v1/chat/completions`
Responses	`/v1/responses`
Anthropic Messages	`/v1/messages`
Gemini native	`/v1beta/models/{model}:generateContent`
Images	`/v1/images/generations`, `/v1/images/edits`
Video	`/v1/videos/generations`
Music	`/v1/music/generations`
3D	`/v1/3d/generations`
Audio	`/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/audio/translations`
Embeddings and rerank	`/v1/embeddings`, `/v1/rerank`
Text translation	`/v1/translations`

Hosted Model Explorer

Clients that support Streamable HTTP can connect to:

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

The hosted explorer is public and exposes open_tokenlab_model_explorer, compare_tokenlab_models, and generate_tokenlab_endpoint_example. Use the local npm server above when you need the generated core/full profiles, local file uploads, or credentialed API operations.

Use It With TokenLab Skills

The MCP server is useful at runtime, while the TokenLab skills repository teaches coding agents how to generate and repair integration code. Use both when available:

MCP server: discover current models, pricing, and endpoint details.
tokenlab-api-integration skill: generate runnable API examples and handle structured TokenLab errors.
tokenlab-model-picker skill: choose strong models for the user’s task.
tokenlab-native-endpoints skill: decide when to use Responses, Anthropic Messages, Gemini, media, audio, embedding, rerank, or translation routes.

Troubleshooting

The client cannot start the server

Confirm Node.js is at least 18.17 and that the client can find npx. Then run npx -y @tokenlabai/mcp-server once in a terminal to surface npm or network errors. A successful stdio launch waits silently for MCP messages; press Ctrl+C after confirming that it starts.

The server is configured but no tools appear

Restart the client and approve or trust the local server when prompted. In Claude Code, run claude mcp list or open /mcp. In VS Code, run MCP: List Servers, select TokenLab, and choose Show Output. In Cursor, open Settings → Tools & MCP and confirm that the server and its tools are enabled.

Claude Code shows Pending approval

Project-scoped .mcp.json servers require workspace trust and explicit approval. Start Claude Code interactively in the project, accept the workspace trust prompt, open /mcp, and approve tokenlab-model-catalog. Use --scope user instead when the server should be private to your account and available across projects.

The model list is empty

Verify that the machine can reach https://api.tokenlab.sh/v1/models. If you override TOKENLAB_API_BASE, make sure it does not include a trailing slash.

The agent still chooses stale model IDs

Ask the agent to call list_models or get_model before hardcoding a model name. Pairing the MCP server with tokenlab-model-picker gives better results.

Can this server call paid TokenLab inference APIs?

Yes. Set TOKENLAB_API_KEY, then use the generated LLM, media, audio, task, file, embedding, rerank, or translation tools. Catalog and pricing tools remain available without a key.

A credentialed tool returns an authentication error

Confirm that TOKENLAB_API_KEY is set in the MCP server’s environment, not pasted into the tool arguments or prompt. Restart the client after changing the configuration. If the key was exposed in a shared file, screenshot, log, or shell history, rotate it before retrying.

The client rejects tool schemas or loads too many tools

Start with TOKENLAB_MCP_TOOL_PROFILE=catalog for six discovery tools or keep the default core profile for 31 tools. The default portable schema mode works with the widest range of clients. Use exact only when complete nested schemas are required, or strict when the model provider requires closed objects and every property in required.

How do I pin or update the package version?

Replace the package argument with @tokenlabai/mcp-server@0.6.17 for a repeatable setup using the currently verified release. To change versions, update that argument in the client configuration and restart the server. Review the public repository before adopting a newer release.

Resources

TokenLab MCP

Product overview and connection options for the Core 31 and Full 80 toolsets

GitHub Repository

Source code and local setup instructions

TokenLab Skills

Maintained agent skills for TokenLab integrations

Model Catalog API

Public model discovery endpoint

llms.txt

Agent-readable TokenLab API overview

Glama MCP Server

View the verified TokenLab MCP Server listing

Glama Model Explorer

Explore models, pricing, and native endpoint examples

MCP.so Listing

Discover TokenLab in the AI & Agents directory

Hosted Model Explorer

Open the public model explorer and remote MCP endpoint

Claude Code MCP Guide

Review Claude Code scopes, approvals, status checks, and MCP configuration

Cursor MCP Guide

Review Cursor configuration locations, tool controls, and security guidance

VS Code MCP Guide

Review VS Code user and workspace configuration, trust, logs, and server management

Compatibility Matrix

Coding Tools

Native SDKs

Frameworks & Platforms

Chat Apps

TokenLab MCP Server

What It Provides

Quickstart

Install in Cursor

Install in VS Code

Configuration Reference

Install From Source

Generated Tool Profiles

Async Media Results

Recommended Agent Workflow

Native Endpoint Guidance

Hosted Model Explorer

Use It With TokenLab Skills

Troubleshooting

Resources

TokenLab MCP

GitHub Repository

TokenLab Skills

Model Catalog API

llms.txt

Glama MCP Server

Glama Model Explorer

MCP.so Listing

Hosted Model Explorer

Claude Code MCP Guide

Cursor MCP Guide

VS Code MCP Guide

​What It Provides

​Quickstart

Install in Cursor

Install in VS Code

​Configuration Reference

​Install From Source

​Generated Tool Profiles

​Async Media Results

​Recommended Agent Workflow

​Native Endpoint Guidance

​Hosted Model Explorer

​Use It With TokenLab Skills

​Troubleshooting

​Resources

TokenLab MCP

GitHub Repository

TokenLab Skills

Model Catalog API

llms.txt

Glama MCP Server

Glama Model Explorer

MCP.so Listing

Hosted Model Explorer

Claude Code MCP Guide

Cursor MCP Guide

VS Code MCP Guide

What It Provides

Quickstart

Configuration Reference

Install From Source

Generated Tool Profiles

Async Media Results

Recommended Agent Workflow

Native Endpoint Guidance

Hosted Model Explorer

Use It With TokenLab Skills

Troubleshooting

Resources