An MCP Server Should Not Flatten Your AI API Into a Prompt Box

hedging8563 — Sat, 11 Jul 2026 19:31:06 +0000

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.

Designing an Async Image API Client That Does Not Lie About Completion

hedging8563 — Sat, 11 Jul 2026 18:35:23 +0000

Image generation is where a seemingly simple API client starts to accumulate production bugs. A request may finish inline for one model, return a task for another, or take a longer path when the input includes edits and uploaded files. Treating every successful HTTP response as a completed image is the fastest way to ship broken retry logic and incorrect user-facing status.

This post adapts the TokenLab article TokenLab Async Image Generation Tasks for Production Apps. The canonical article contains the full implementation discussion; this version focuses on the contract decisions that matter when building an integration.

The response is a delivery decision, not just a payload

An image endpoint can return either a completed representation or an asynchronous task. The client should inspect the response envelope and normalize the delivery mode before it touches application state:

type Delivery =
  | { mode: "sync"; terminal: true }
  | { mode: "async"; task_id: string; status: string; terminal: false };

The important invariant is that mode and terminal state come from the API contract. Do not infer completion from a missing progress field, a truthy data property, or a fast response time. Progress is useful when present, but it is not the completion signal.

Poll by task identity, not by the original request

When the server returns an async task, persist the task ID and the provider-neutral status. A worker can then poll the task endpoint with bounded backoff:

async function waitForTask(id: string) {
  for (let attempt = 0; attempt < 60; attempt += 1) {
    const task = await getTaskStatus(id);
    if (task.status === "succeeded") return task.result;
    if (["failed", "cancelled", "expired"].includes(task.status)) {
      throw new Error(`Media task ${id} ended as ${task.status}`);
    }
    await sleep(Math.min(1000 * 2 ** Math.min(attempt, 5), 30_000));
  }
  throw new Error(`Media task ${id} exceeded the polling budget`);
}

This makes retries explicit. A network timeout after task creation is not proof that the task failed, so blindly replaying the generation request can create duplicate work or duplicate billing. The safer recovery is to reconcile the task ID first.

Keep native request shapes visible

The integration should preserve image prompts, edit inputs, response formats, model IDs, and file references instead of flattening them into a generic chat prompt. That gives callers a stable place to express image-specific behavior and lets the same client support OpenAI-compatible and native endpoint families without pretending they are identical.

For production systems, the practical checklist is:

record the request ID and task ID separately;
persist the last observed status and terminal timestamp;
treat succeeded, failed, cancelled, and expired as terminal states;
make the poller idempotent and bounded;
keep binary delivery separate from JSON task metadata;
show the user whether the result is ready, queued, or failed.

The full TokenLab implementation notes, current model examples, and image/edit endpoint references are in the canonical blog post. TokenLab's public image API documentation is the source of truth for request and response fields.

DEV Community: hedging8563