TokenLab MCP Server

MCP server for TokenLab model discovery, pricing, native endpoint guidance, and optional inference helpers.

OpenAPI-generated Model Context Protocol server for TokenLab public model discovery, pricing, native LLM endpoints, 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, and text translation.

The checked-ingenerated/tools.jsonmanifest is generated from TokenLab's public OpenAPI document plus the small MCP-only overlay incontract/mcp-overlay.json. Version 0.6.17 generates 78 endpoint tools; with the two MCP-only composite discovery tools, the full profile returns 80 tools fromtools/list.

The total registered count is the number returned bytools/list. All profiles includecompare_modelsandget_api_overview, producing totals of 6, 31, and 80 tools. Realtime and streaming-only operations are excluded because stdio MCP tool calls return one final result. API operations that acceptstreamfix it internally tofalsewithout exposing a booleanconstto provider adapters, and the Gemini query-string API key is intentionally hidden from tool arguments.

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 keepcoreat no more than 60 KB and depth 8, andfullat no more than 100 KB and depth 8 for the completetools/listresponse. Tests also run the full profile through the Google AI SDK version used by the observed OpenCode/Gemini failure.

SetTOKENLAB_MCP_TOOL_PROFILE=catalogfor the smallest public-only tool list orTOKENLAB_MCP_TOOL_PROFILE=fullfor the broad developer API. SetTOKENLAB_MCP_SCHEMA_MODE=exactonly when a client needs the complete nested JSON Schema and can accept its larger/deeper tool payload. Usestrictfor providers that require every property to be listed inrequiredand every object to setadditionalProperties: 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 ingenerated/tools.json.

The smallergenerated/public-contract.jsonis 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.

Agent-assisted installers can followllms-install.mdfor a credential-safe setup and verification flow.

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

{ "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. SetTOKENLAB_API_KEYwhen 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 toTOKENLAB_ARTIFACT_DIRand returned as a path with MIME type and byte count.

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 underresponseand add a normalizeddeliverysummary:

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

Usedelivery.modeinstead of assuming all image requests are synchronous. For async tasks, callget_task_statuswith{ "id": delivery.task_id }untildelivery.terminalistrue. Completion is determined fromstatus, not from an optional progress field.

- TOKENLAB_API_BASE: optional, defaults tohttps://api.tokenlab.sh
- TOKENLAB_API_KEY: optional; required for text inference, multimodal generation, async task, embedding, rerank, and translation tools
- TOKENLAB_MCP_TOOL_PROFILE: optional,catalog,core(default), orfull
- TOKENLAB_MCP_SCHEMA_MODE: optional,portable,exact, orstrict; defaults to the selected profile's tested mode
- TOKENLAB_REQUEST_TIMEOUT_MS: optional request timeout in milliseconds, defaults to120000
- TOKENLAB_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 asdata:image/png;base64,.... If an MCP caller labels a recognized PNG, JPEG, WebP, or GIF payload asapplication/octet-stream, the server corrects that generic MIME before forwarding. An unrecognized generic binary payload is rejected locally with a precise input error.

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 rungit pull --ff-onlybefore a manual contract sync.contract:checkproves internal consistency only;contract:source-checkproves freshness against the canonical source. The scheduledSync TokenLab OpenAPI contractworkflow runs the full write sequence and commits only the verified OpenAPI snapshot and generated manifest tomain. A failed fetch, stale local branch, dirty generated output, generation error, schema compilation error, or test leaves the tracked contract unchanged.

This repository includesserver.jsonfor the official MCP Registry.

- npm package:@tokenlabai/mcp-server@0.6.17
- MCP registry name:io.github.hedging8563/tokenlab
- package.json.mcpName:io.github.hedging8563/tokenlab
- Bump the matching versions inpackage.json,package-lock.json, andserver.json.
- Push a matching tag such asv0.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 frommainto republish only the current MCP Registry metadata. No npm or MCP Registry token is stored in GitHub.

Use thecatalogprofile when no credentialed tools are needed. KeepTOKENLAB_API_KEYin 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.

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

Build and deploy full-stack Next.js apps with 98 tools for React, AWS, and MongoDB