Most AI integrations start with a chat-completions-shaped abstraction. That is a useful default, but it becomes a problem when an agent has to work with more than text: OpenAI Responses, Anthropic content blocks and tools, Gemini multimodal parts, uploaded files, or a media task that does not complete in the initial response.
The practical goal for an MCP server is not to make every API look identical. It is to give an agent a small discovery surface first, then preserve the documented request shape when a workflow needs a native endpoint.
TokenLab MCP Server 0.5.0 is generated from TokenLab's public OpenAPI contract. Its catalog profile exposes six public discovery tools, the default profile exposes 31 tools, and the full profile exposes 78. Public catalog and pricing tools do not require a TokenLab API key; credentialed inference and task tools do.
Start with discovery
Before an agent writes an API call, it should establish three facts:
- the model ID exists now;
- the model supports the endpoint family the task needs;
- the current price and modality fit the workflow.
That is what list_models, get_model, get_model_pricing, and get_api_overview are for. It is safer than copying a model name out of an old example and discovering later that it belongs to a different endpoint family.
Install the stdio server with a minimal configuration:
{
"mcpServers": {
"tokenlab": {
"command": "npx",
"args": ["-y", "@tokenlabai/mcp-server@0.5.0"]
}
}
}
Add TOKENLAB_API_KEY only in the MCP client's secret environment when the agent needs credentialed operations. Discovery can remain keyless.
Keep the endpoint family explicit
There is no single request format that faithfully describes all AI APIs. A generic chat tool is right for an OpenAI-compatible chat-completion request. It is not a substitute for a Responses workflow, Anthropic's structured content blocks, Gemini's multimodal parts, or multipart file input.
The server therefore exposes endpoint-specific tools generated from the public contract. The agent chooses the endpoint family deliberately rather than converting every payload into a text prompt and hoping the missing behavior does not matter.
That gives a useful separation of concerns:
- discovery decides what is currently available;
- the endpoint tool decides how to make the request;
- application code decides when a model or fallback is appropriate.
Treat media delivery as part of the contract
Image generation and editing may return a finished result or an async task depending on the selected model and request. Video, music, and 3D creation always return an async task. A client should not treat HTTP success as proof that a binary result is ready.
The MCP response keeps the native TokenLab response and adds a normalized delivery summary. A consumer can branch on its mode and task identity without guessing from a partial progress field:
if (result.delivery.mode === "async") {
await pollTask(result.delivery.task_id);
} else {
useCompletedResult(result.response);
}
Persist the task ID before retrying a timed-out call. If a request was accepted but the client lost the response, replaying the original generation request can create duplicate work. Reconciliation by task identity is the safer recovery path.
Keep the tool surface reviewable
The package exposes its generated tool manifest, including tool schemas, HTTP bindings, auth requirements, and task behavior. That matters because an agent should not receive broad, persistent approval for every operation merely because one read-only model lookup is safe.
Use the catalog profile for public inspection, the default profile for common developer work, and the full profile only when the agent genuinely needs the broader API. Review human-confirmation settings for billable and destructive calls in the MCP client itself.
The complete install guides, field tables, and client-specific examples are in the TokenLab MCP Server documentation. The public repository contains the generated manifest and tests.
Top comments (0)