MCP

MCP Server

View as Markdown

Mesh runs a built-in Model Context Protocol (MCP) server, so any MCP-compatible agent or client — Claude Code, Claude Desktop, Cursor, or your own agent framework — can use Mesh’s models and tools directly, without writing any Mesh-specific HTTP code.

The server exposes the Mesh API surface as MCP tools: an agent can run chat completions, reason with the Responses API, generate and edit images, create embeddings, moderate content, search the web, query your RAG files, manage prompt templates, and check your balance — all authenticated with your existing Mesh API key.

The MCP server is a thin layer over the same routes as the REST API. Every tool call runs the identical authentication, rate-limit, spend-cap, balance, and usage-logging pipeline as a direct API call, and is billed to the same key.

Connection details

Endpointhttps://api.meshapi.ai/mcp
TransportStreamable HTTP
AuthenticationAuthorization: Bearer rsk_... (your Mesh API key)

You connect with the same rsk_ API key you use for the REST API — no separate credential or OAuth flow. Pass it in the Authorization header when registering the server with your client.

Connect a client

$claude mcp add --transport http mesh-api https://api.meshapi.ai/mcp \
>  --header "Authorization: Bearer rsk_YOUR_KEY"

Then, in a session, ask Claude to use the Mesh tools (e.g. “use mesh-api to draft a reply with openai/gpt-4o-mini”).

Keep your rsk_ key secret — it authorizes billable calls against your account. Treat an MCP client config that embeds the key like any other secret store, and rotate the key from the dashboard if it leaks.

Available tools

Tools mirror the REST API one-to-one. Inputs are OpenAI-shaped, so anything you know from the API reference carries over directly.

Inference

ToolWhat it doesBilled
chatChat completion against any catalog model (model, messages, optional temperature, max_tokens)Yes
responsesResponses API for reasoning models / hosted tools (model, input, max_output_tokens, reasoning_effort)Yes
embeddingsEmbedding vectors for one or more texts (model, input)Yes
moderationsClassify text for policy violations (input, optional model)Yes
compareRun the same messages across several models (models, messages, optional comparison_model)Yes
router_selectAsk the Auto Router which model best fits (messages) — no completion is runNo
generate_imageGenerate image(s) from a prompt (prompt, model, n, size, response_format)Yes
edit_imageEdit an image with a prompt (model, prompt, image, optional mask) — image/mask are data URLs, base64, or URLsYes

RAG & search

ToolWhat it doesBilled
web_searchWeb search with ranked results (query, max_results, search_depth)Yes
file_searchSemantic search over your uploaded files (query, top_k, optional file_ids)Yes
upload_fileUpload a document to RAG (file_name, mime_type, content_base64, embed); embedding runs asynchronouslyNo
list_filesList your uploaded RAG filesNo
get_fileStatus / metadata for one file (file_id) — poll until embedding_status is readyNo

Catalog & account

ToolWhat it doesBilled
list_modelsList catalog models, optionally filtered by providerNo
list_voicesList text-to-speech voices available to your keyNo
get_balanceCurrent credit balance for your accountNo

Prompt templates

ToolWhat it doesBilled
list_templatesList prompt templates for your orgNo
get_templateGet one template (template_id)No
create_templateCreate a template (name, optional system, messages, model, description, variables)No
update_templateUpdate a template (template_id + fields to change)No
delete_templateDelete a template (template_id)No

The server also exposes a resource, mesh://models, that returns the full model catalog as JSON — useful for clients that consume MCP resources rather than calling list_models.

Example: give an agent a document Q&A tool

A typical agent flow — upload a file, wait for embeddings, then answer questions grounded in it — is three tool calls:

1

Upload the document

Call upload_file with the file’s bytes base64-encoded. You get back a file_id.

1{
2  "name": "upload_file",
3  "arguments": {
4    "file_name": "handbook.pdf",
5    "mime_type": "application/pdf",
6    "content_base64": "JVBERi0xLjc...",
7    "embed": true
8  }
9}
2

Wait for embeddings

Poll get_file with the file_id until embedding_status is ready. Embedding is asynchronous, so a freshly uploaded file is not immediately searchable.

3

Search and answer

Call file_search with a natural-language query, then feed the returned passages into chat to get a grounded answer.

Authentication & billing

  • Auth: the Authorization: Bearer rsk_... header is validated before any tool runs. A missing or invalid key returns 401; a suspended key returns 403.
  • Limits & billing: billed tool calls inherit the key’s per-key rate limits, spend cap, model allow-list, and credit balance — exactly as a direct REST call. If a call would exceed a limit or your balance is insufficient, the tool returns an error carrying the Mesh message (e.g. “Insufficient balance.”).
  • Free tools: the catalog/account reads (list_models, list_voices, get_balance), the RAG file reads (list_files, get_file, upload_file), template management, and router_select are not billed. Everything under Inference, plus web_search and file_search, is billed.
  • Usage tracking: every billed tool call is logged to your usage history just like a REST request, so MCP traffic shows up in the dashboard and usage reports.

Limitations

Tool results are returned as a single payload — there is no token-by-token streaming of a chat/responses result over MCP. For streaming, use the REST API or an SDK.

The following Mesh capabilities are not yet exposed as MCP tools — use the REST API or an SDK for them:

  • Audio: text-to-speech and speech-to-text (transcription/translation)
  • Video generation and the async Batch API
  • Realtime audio (bidirectional WebSocket)
  • Usage-report queries

Troubleshooting

SymptomLikely cause / fix
401 Unauthorized when connectingMissing or malformed Authorization header. It must be Bearer rsk_....
403 ForbiddenThe key is suspended — check it in the dashboard.
Tool returns “Insufficient balance.”Add credits, or the call exceeded your spend cap.
file_search returns nothing for a just-uploaded fileEmbedding is still processing — poll get_file until embedding_status is ready.
A model isn’t callableIt may be outside your key’s model allow-list, or not in the catalog — check list_models.