Enables AI clients to discover models, compare pricing, and perform multimodal generation including text, image, video, music, and 3D assets.
Also known as hedging8563/tokenlab-mcp-server, tokenlab-mcp-server, @tokenlabai/mcp-server
- Stars
- 1
- Tools
- 32
- Downloads, 30 days
- —
- Latest version
- 0.6.48
- Last commit
- Nov 13, 2026
- License
- MIT
What is TokenLab MCP?
TokenLab enables AI clients to discover models, compare pricing, and perform multimodal generation including text, image, video, music, and 3D assets. It exposes 32 tools, such as cancel_task, create_3d_model, create_anthropic_message.
Summary generated from the project's README
About TokenLab MCP server
TokenLab MCP Server provides a bridge for AI agents to interact with a wide range of machine learning models and generative services. Developers can use this server to discover available models, compare pricing, and execute multimodal tasks. It supports text inference, image generation, video, music, 3D asset creation, and text translation. The server can be run locally via npx or through Docker containers.
Users can choose between different tool profiles depending on their needs. The catalog profile allows for public model discovery and pricing without an API key. The core profile provides standard capabilities like chat completions, embeddings, and rerank. The full profile exposes the entire developer API, including webhook management and batch operations. While catalog tools are public, accessing credentialed tools like text inference or media generation requires a TOKENLAB_API_KEY set in the environment.
This server handles complex media workflows by managing asynchronous tasks for video and music. Large binary responses are saved to a local directory defined by TOKENLAB_ARTIFACT_DIR rather than being sent inline. It also includes specialized tools for typed decisions and embedding generation.
What you can do with it
- 1Compare model pricingAn agent can inspect the public catalog to find the most cost-effective model for a specific task.
- 2Generate multimodal contentA developer can instruct an AI to create various types of media including images, video, and music.
- 3Manage asynchronous media tasksAn AI client can poll for the status of a long-running video or music generation job.
Written from the project's README. Every use case is checked against a quote from it.
How to install TokenLab MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall TokenLab MCP in Claude Code
$ claude mcp add --env 'TOKENLAB_API_KEY=<YOUR_TOKENLAB_API_KEY>' --env 'TOKENLAB_MANAGEMENT_TOKEN=<YOUR_TOKENLAB_MANAGEMENT_TOKEN>' tokenlab-mcp-server -- npx -y @tokenlabai/mcp-serverInstall TokenLab MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"tokenlab-mcp-server": {
"command": "npx",
"args": [
"-y",
"@tokenlabai/mcp-server"
],
"env": {
"TOKENLAB_API_KEY": "<YOUR_TOKENLAB_API_KEY>",
"TOKENLAB_MANAGEMENT_TOKEN": "<YOUR_TOKENLAB_MANAGEMENT_TOKEN>"
}
}
}
}Install TokenLab MCP in VS Code
.vscode/mcp.json
{
"servers": {
"tokenlab-mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@tokenlabai/mcp-server"
],
"env": {
"TOKENLAB_API_KEY": "<YOUR_TOKENLAB_API_KEY>",
"TOKENLAB_MANAGEMENT_TOKEN": "<YOUR_TOKENLAB_MANAGEMENT_TOKEN>"
}
}
}
}Install TokenLab MCP in VS Code CLI
$ code --add-mcp '{"name":"tokenlab-mcp-server","type":"stdio","command":"npx","args":["-y","@tokenlabai/mcp-server"],"env":{"TOKENLAB_API_KEY":"<YOUR_TOKENLAB_API_KEY>","TOKENLAB_MANAGEMENT_TOKEN":"<YOUR_TOKENLAB_MANAGEMENT_TOKEN>"}}'Install TokenLab MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"tokenlab-mcp-server": {
"command": "npx",
"args": [
"-y",
"@tokenlabai/mcp-server"
],
"env": {
"TOKENLAB_API_KEY": "<YOUR_TOKENLAB_API_KEY>",
"TOKENLAB_MANAGEMENT_TOKEN": "<YOUR_TOKENLAB_MANAGEMENT_TOKEN>"
}
}
}
}Install TokenLab MCP in Codex
$ codex mcp add tokenlab-mcp-server --env 'TOKENLAB_API_KEY=<YOUR_TOKENLAB_API_KEY>' --env 'TOKENLAB_MANAGEMENT_TOKEN=<YOUR_TOKENLAB_MANAGEMENT_TOKEN>' -- npx -y @tokenlabai/mcp-serverInstall TokenLab MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.tokenlab-mcp-server] command = "npx" args = ["-y", "@tokenlabai/mcp-server"] [mcp_servers.tokenlab-mcp-server.env] TOKENLAB_API_KEY = "<YOUR_TOKENLAB_API_KEY>" TOKENLAB_MANAGEMENT_TOKEN = "<YOUR_TOKENLAB_MANAGEMENT_TOKEN>"
Install TokenLab MCP in Gemini CLI
$ gemini mcp add -s user -e 'TOKENLAB_API_KEY=<YOUR_TOKENLAB_API_KEY>' -e 'TOKENLAB_MANAGEMENT_TOKEN=<YOUR_TOKENLAB_MANAGEMENT_TOKEN>' tokenlab-mcp-server npx -- -y @tokenlabai/mcp-serverInstall TokenLab MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"tokenlab-mcp-server": {
"command": "npx",
"args": [
"-y",
"@tokenlabai/mcp-server"
],
"env": {
"TOKENLAB_API_KEY": "<YOUR_TOKENLAB_API_KEY>",
"TOKENLAB_MANAGEMENT_TOKEN": "<YOUR_TOKENLAB_MANAGEMENT_TOKEN>"
}
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @tokenlabai/mcp-server 0.6.48 in an isolated container with no network and no keys. It answered and listed 32 tools.
TokenLab MCP tools 32
Read from the server with tools/listcancel_taskActionCancels a queued asynchronous task when cancellation is supported for the selected task. Cancellation currently supports queued Seedance video tasks (`seedance-2.0` and `seedance-2.0-fast`) while they are still waiting to run. Tasks that are already processing, completed, failed, expired, or unsupported are not cancelled.
create_3d_modelActionCreates a 3D model generation task using Tripo3D. Returns a task ID for polling.
create_anthropic_messageActionCreates a model response using Anthropic's native request format. Supports Claude models with vision and streaming. **Authentication:** Use `x-api-key` header or `Authorization: Bearer` header.
create_chat_completionActionCreate an OpenAI-compatible chat completion. For inline image_url data URLs, declare the byte-accurate image MIME type. The MCP boundary corrects recognized PNG, JPEG, WebP, and GIF payloads declared as application/octet-stream and rejects unrecognized generic binary image payloads before sending a billable request.
create_embeddingActionCreates an embedding vector representing the input text.
create_gemini_contentActionGenerates content using the Gemini GenerateContent request shape. The model details must advertise Gemini requests and the model must be available. ProtoJSON lowerCamelCase and original proto snake_case field names are preserved. Unknown fields are accepted on a best-effort basis; model-specific support is not guaranteed. **Authentication:** Use `?key=` query parameter, `x-goog-api-key` header, or `Authorization: Bearer` header.
create_imageActionCreates an image given a prompt.
create_image_fileActionCreates an image given a prompt.
create_multimodal_embeddingActionCreates embeddings for multimodal input items. Text input is generally available; image input may require feature enablement.
create_musicActionCreates a music generation task using Suno. Returns a task ID for polling.
create_responseActionCreates a response using the OpenAI Responses API request shape. The model details must advertise the Responses request format and the model must be available. Unknown fields are accepted on a best-effort basis; model-specific support is not guaranteed.
create_speechActionGenerates audio from the input text (Text-to-Speech).
Show all 32 toolsShow fewer tools
create_videoActionCreates an asynchronous video generation task. The response returns a canonical task ID and usually a preferred `poll_url`; clients should poll `poll_url` first, or use `/v1/tasks/{id}` as the fixed status endpoint.
delete_fileActionDeletes a batch file or a bound image/reference file. When the request includes anthropic-beta: files-api-2025-04-14, the route uses Anthropic Files API mode for the bound workspace.
edit_imageActionEdits an image using multipart image uploads, JSON image URLs, or the official JSON images array for supported GPT Image models.
edit_image_fileActionEdits an image using multipart image uploads, JSON image URLs, or the official JSON images array for supported GPT Image models.
evaluate_decisionsActionEvaluate typed Noul probability, Choice, and Score questions against shared state using the native System One endpoint. Discover a decision model with list_models/get_model first. Returns synchronous structured decisions, not chat text. A decision does not authorize an external action.
get_modelRead-onlyRetrieves current model details, including supported operations, request parameters, request endpoints, selector limits, and pricing when available. Non-chat integrations should read these current model-specific request details before creating a request.
get_model_pricingRead-onlyRetrieves pricing-only detail for one model. No API key is needed. Use it to explain a price, not to build a request.
get_pricingRead-onlyReturns the public pricing surface for active models, with optional provider and tag filters.
get_task_statusRead-onlyRetrieves the status and result of an asynchronous generation task. Prefer the `poll_url` returned by the create response; `/v1/tasks/{id}` is the canonical fixed status endpoint for video, music, and 3D jobs.
list_filesRead-onlyList files
list_modelsRead-onlyLists the currently available models. Use `view=compact` for model selection and `view=full` for the existing OpenAI-compatible discovery shape. Native API calls default to `full`; integrations may choose `compact` as their default. Non-chat recommendations are available through `recommended_for`.
rerank_documentsActionReranks documents by relevance to a query using semantic similarity.
retrieve_fileRead-onlyRetrieve file
retrieve_file_contentRead-onlyRetrieve file content
transcribe_audioActionTranscribes audio into text (Speech-to-Text).
translate_audioActionTranscribes audio and translates the result to English.
translate_textActionTranslates text into a target language using the current translation request format.
upload_fileActionUploads a TokenLab/OpenAI-compatible batch or image file. With anthropic-beta: files-api-2025-04-14, uploads an Anthropic Files resource without a purpose field and returns Anthropic file metadata.
compare_modelsRead-onlyCompare public TokenLab model details and pricing for several model IDs.
get_api_overviewRead-onlyFetch TokenLab's agent-readable API overview.
Configuration
TOKENLAB_API_KEYSecretOptional TokenLab API key. Required for LLM inference, multimodal generation, async task, embedding, rerank, and translation tools.
TOKENLAB_MANAGEMENT_TOKENSecretOptional workspace Management Token (mt-...) for webhook tools in the full profile. Separate from inference API keys; never put it in tool arguments.
TOKENLAB_API_BASEOptional TokenLab API base URL. Defaults to https://api.tokenlab.sh.
TOKENLAB_ARTIFACT_DIROptional local directory for response artifacts that are not returned inline.
TOKENLAB_MCP_INLINE_BYTESOptional maximum response size returned inline. Defaults to 2097152 bytes.
TOKENLAB_MCP_MAX_FILE_BYTESOptional maximum local upload size per file. Defaults to 104857600 bytes.
TOKENLAB_MCP_SCHEMA_MODEOptional tool schema mode: portable, exact, or strict. Defaults to the selected profile's tested mode.
TOKENLAB_MCP_TOOL_PROFILEOptional generated tool profile: catalog, core (default), or full.
TOKENLAB_REQUEST_TIMEOUT_MSOptional request timeout in milliseconds. Defaults to 120000.
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubTokenLab 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.46 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.
The smaller 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
structuredContentwhile 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;
exactmode 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_modelandbuild_tokenlab_requestprompts 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
npm install
npm start
Install from npm:
npx -y @tokenlabai/mcp-server
Agent-assisted installers can follow llms-install.md for a credential-safe setup and verification flow.
Run in Docker:
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:
{
"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:
{
"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 tohttps://api.tokenlab.shTOKENLAB_API_KEY: optional; required for text inference, multimodal generation, async task, embedding, rerank, decision, and translation toolsTOKENLAB_MCP_TOOL_PROFILE: optional,catalog,core(default), orfullTOKENLAB_MCP_SCHEMA_MODE: optional,portable,exact, orstrict; defaults to the selected profile's tested modeTOKENLAB_REQUEST_TIMEOUT_MS: optional request timeout in milliseconds, defaults to120000TOKENLAB_MCP_MAX_FILE_BYTES: optional maximum local upload size per file, defaults to104857600(100 MiB)TOKENLAB_MCP_INLINE_BYTES: optional maximum binary/JSON response size returned inline, defaults to2097152(2 MiB)TOKENLAB_ARTIFACT_DIR: optional output directory for non-inline response artifacts, defaults to the OS temp directory undertokenlab-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.
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.46 - MCP registry name:
io.github.hedging8563/tokenlab package.json.mcpName:io.github.hedging8563/tokenlab
For a new release:
- Bump the matching versions in
package.json,package-lock.json, andserver.json. - Push a matching tag such as
v0.6.0. - 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.
Each API request sends X-TokenLab-Client-Source: mcp-<tool name> (for example mcp-create_image) so TokenLab can count which tools are used. Reading the tokenlab://api/overview resource sends mcp-resource-api_overview. The header holds only the lowercased tool name, cut to 64 characters, and no tool arguments.
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. 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 for payloads, signing, deduplication and delivery history.
TokenLab MCP questions
How do I add TokenLab MCP to Claude Code?
Run claude mcp add --env 'TOKENLAB_API_KEY=<YOUR_TOKENLAB_API_KEY>' --env 'TOKENLAB_MANAGEMENT_TOKEN=<YOUR_TOKENLAB_MANAGEMENT_TOKEN>' tokenlab-mcp-server -- npx -y @tokenlabai/mcp-server in your terminal. Add --scope user to make it available in every project.
How do I add TokenLab MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does TokenLab MCP provide?
It exposes 32 tools, including cancel_task, create_3d_model, create_anthropic_message, create_chat_completion, create_embedding.
Do I need an API key to use TokenLab?
No API key is required for public catalog and pricing operations, but you must set a TOKENLAB_API_KEY for credentialed tools like text inference and multimodal generation.
How can I handle long-running media generation tasks?
Video, music, and 3D tools return an async task; you should use the get_task_status tool with the provided task ID until the delivery mode is terminal.
What are the different tool profiles available?
The server offers three profiles: 'catalog' for public discovery and pricing, 'core' (default) for standard multimodal and text tasks, and 'full' for every available developer API operation.