Agents
MCP Server
A hosted Model Context Protocol server. It gives agents the live model catalog, prices in US dollars, these docs, the glossary and ready-to-run code snippets as tools. With an API key, agents can run models directly over MCP: chat, image, video, speech. Billed like the API. Client setup for Claude Code, Cursor, Claude Desktop and VS Code is on the MCP page.
- Endpoint
- https://railwail.com/api/mcp
- Transport
- Streamable HTTP
- Protocol
- 2025-06-18 · 2025-03-26
- Auth
- optional Bearer rw_live_…
- Tools
- 22
Setup in one line
Claude Code, read-only, no account needed:
Terminal
claude mcp add --transport http railwail https://railwail.com/api/mcpWith a key (put it in RAILWAIL_API_KEY first), so your agent can also run models. Other clients and the key variants for each are on the MCP page.
Terminal
claude mcp add --transport http railwail https://railwail.com/api/mcp \
--header "Authorization: Bearer $RAILWAIL_API_KEY"Transport and methods
JSON-RPC 2.0 over POST https://railwail.com/api/mcp, answered with application/json (no SSE stream, no sessions). Send Accept: application/json, text/event-stream as the Streamable HTTP spec asks. The server negotiates protocol version 2025-06-18 and also accepts 2025-03-26. The machine-readable description is at https://railwail.com/.well-known/mcp.json.
| Method | What it does |
|---|---|
initialize | Negotiates the protocol version and returns server info, capabilities (tools) and usage instructions. |
notifications/initialized | Accepted with HTTP 202 and an empty body, like every notification. |
ping | Returns an empty result. |
tools/list | All tools with their JSON Schema input and, where set, annotations such as readOnlyHint. |
tools/call | Runs one tool. The result is JSON as text in content[0].text; failures set isError: true. |
GET and DELETE are not part of this server: there is no server-to-client stream and no session to end.
Try it (free, no key)
Both calls are anonymous and cost nothing. The first lists the tools, the second searches the catalog.
tools/list
curl -s https://railwail.com/api/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'tools/call · search_models
curl -s https://railwail.com/api/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_models","arguments":{"query":"image","limit":3}}}'Or call any read-only tool from here; the answer comes from the same server your agent talks to.
search_models
Nur lesen · kostenlosSearch the live Railwail model catalog by free text and filters (category, provider, minimum context window, maximum token price). Returns only models the API can run right now, each with its price and billing unit (per token, per image, per second of output, per 1,000 characters or per GPU-second), context window and latency. Older models carry lifecycle.successor_slug; a query naming a duplicate or removed model finds the model to use instead. Start here for any question of the form 'which model can do X' or 'what does Railwail offer for Y'.
querystringFree text matched against name, slug, description and tags.(≤ 200 chars)
categorystringOne of: text, image, video, audio, speech_tts, transcription_stt, embedding, code, multimodal, vla_robotics.(≤ 64 chars)
providerstringProvider slug, e.g. openai, anthropic, google, mistral, deepseek, xai, meta, black-forest-labs.(≤ 64 chars)
tagstringRequire a catalog tag, e.g. vision, coding, svg.(≤ 64 chars)
min_context_windownumberMinimum context window in tokens.(0–100M)
max_input_price_per_1mnumberMaximum input price in USD per 1 million tokens. Keeps token-priced models only.(0–1M)
featured_onlyboolean—
limitnumberMax results, default 10, cap 50.(1–50)
kopiert den Aufruf als curl
Wird anonym an /api/mcp gesendet. Kostenlos; zählt zu den 30 Anfragen pro Minute deiner IP.
Antwort
Ruf das Tool auf, um die Live-Antwort aus dem Katalog zu sehen.
Tools
Rendered from the server's own tools/list. Prices in every answer are US dollars at the price the API charges (1 credit = USD 0.01); models that cannot run right now are left out of lists and rankings.
| Tool | Required arguments | What it does |
|---|---|---|
search_models | — | Search the live Railwail model catalog by free text and filters (category, provider, minimum context window, maximum token price). Returns only models the API can run right now, each with its price and billing unit (per token, per image, per second of output, per 1,000 characters or per GPU-second), context window and latency. Older models carry lifecycle.successor_slug; a query naming a duplicate or removed model finds the model to use instead. Start here for any question of the form 'which model can do X' or 'what does Railwail offer for Y'. |
get_model | model | Everything Railwail knows about one model: whether the API can run it right now, its price and billing unit, context window, max output tokens, supported formats, latency, tags, how to run it (run: the MCP tool, the key scope and the input fields, for video also the image fields the model takes), plus the deep dive where one exists (lab, architecture, training data, licence, known limitations, papers). A duplicate or removed model answers with use_instead when there is a runnable model to use, an older one names its successor. Use this before making claims about a model's licence or weaknesses instead of relying on training data. |
compare_models | models | Compare two to four models side by side on price and billing unit, context window, max output, latency and provider, with the concrete deltas spelled out. Models the API cannot run right now are marked available:false. Mirrors the on-site comparison pages. |
estimate_cost | models | Estimate the monthly Railwail bill for a workload. Give up to ten model slugs plus the volumes that match their billing unit: tokens for text and embedding models, requests for image, video and GPU-second models (each priced as one default API call), characters for speech. Returns the cost per model in USD (*_usd fields) and credits, cheapest first. Models the API cannot run right now are listed separately and never ranked. Use this for 'what would X cost' rather than guessing from memory. |
recommend_model | task | Turn a plain-language task description plus constraints (budget, context window, latency ceiling, modality) into a short, reasoned shortlist of Railwail models the API can run right now. Every entry carries a reason and a URL. Returns an explicit empty result (no_match: true) when nothing in the catalog fits the task. Use this when the user describes what they want to build rather than naming a model. |
get_rankings | dimension | Top runnable models on one live dimension: cost-input, cost-output, context, popular, latency, newest, rating or code. Answers 'what is currently the cheapest / fastest / longest-context model' with numbers from the catalog instead of stale training knowledge. Popularity counts completed jobs of the last 30 days. |
get_integration_snippet | language, task | Runnable code for a concrete case: language (python, typescript, curl, go) times task (chat, image, embedding, video, tts, stt) times model slug. Returns the correct endpoint, base URL, request format and real model identifier so the user can copy it straight into their project instead of being pointed at the docs. Without a model the most used runnable model of the task is chosen. |
get_migration_guide | provider | The Railwail migration guide for one of the covered providers (openai, anthropic, azure-openai, google-ai, mistral, cohere, deepseek, groq, together-ai, fireworks, replicate, runway, stability-ai, elevenlabs, huggingface, openrouter, perplexity, xai, anyscale, deepinfra): what changes, step by step, the endpoint and model mapping checked against the live API, plus the current platform facts. |
search_docs | query | Full-text search across the Railwail developer documentation: quickstart, authentication, the SDK reference (rw.run, rw.chat, rw.image, rw.embed, rw.models, rw.job), the REST endpoints for chat, images, embeddings, models and jobs, OpenAI compatibility, rate limits, error codes and the setup of this MCP server. Use it for "how do I ..." questions about the API. |
lookup_glossary | term | Look up an AI term in the Railwail glossary (250 entries, aliases included): short and long definition, related terms, and related models as runnable catalog slugs. Use this instead of paraphrasing a general definition when the user asks what something like MoE, quantisation or speculative decoding means. |
get_pricing_and_limits | — | The commercial and operational frame in one call: how prepaid credits are bought and billed (1 credit = USD 0.01), which billing unit each kind of model uses, the per-key rate limits and the limits of this MCP server, and what Railwail does not charge for. Saves scraping the pricing page and the rate-limit doc separately. |
get_platform_facts | — | Facts about Railwail itself that come up before a buying decision: what it is, where it runs, how many models the API can run right now, what the chat endpoint supports, what this MCP server can do with and without an API key, GDPR position, which providers are covered, and the official contact and policy URLs. Use this instead of guessing, and link the page that is actually binding. |
estimate_fine_tuning | model | Price and duration of fine-tuning a robotics model on a LeRobot dataset, without an API key and without booking anything: estimated GPU seconds (steps x the model's seconds per step, within its limits), the GPU price per hour, estimated_credits, and held_credits, the hold booked when the job is created (1 credit = USD 0.01; the unused part is refunded when the job ends). Also returns max_steps, the dataset format the model trains on and its license. An unknown or untrainable model answers with the list of trainable models. create_fine_tuning_job starts the job (API key with the fine_tuning scope). |
chat_completionneeds an API key | model, messages | Run a chat, code or multimodal model and return its answer. Needs an API key (Authorization: Bearer rw_live_... on the MCP connection) with the 'chat' scope, and is billed like POST /api/v1/chat/completions: prepaid credits, 1 credit = USD 0.01, the hold covers the prompt plus max_tokens and the rest is refunded. The key's IP allowlist, rate limit and the account's monthly spending limit apply. max_credits caps the final price: the run is refused before anything is charged when the most it can cost (every input byte counted as a token, plus max_tokens) is higher, and always when the messages carry image, audio or file parts. Returns { text, finish_reason, usage, credits_charged, job_id }. Without an API key the call returns isError with how to create one (https://railwail.com/en/dashboard/settings/api-keys); the other tools of this server need no key. |
run_modelneeds an API key | model, input | Run an image, video, speech (text-to-speech), embedding or chat model through the same API route and billing as a direct API call. input is the request body of the model's endpoint without model: get_model lists it under run.input_fields (images: prompt, n, size ...; video: prompt, duration_sec, aspect_ratio, the image fields in run.image_fields; speech: input, voice; embeddings: input; chat: messages or prompt). Needs an API key with the scope of the model's category (images, video, audio, embeddings or chat). Credits are held before the run (1 credit = USD 0.01) and failed runs are refunded. max_credits caps the final price: a run is refused before anything is charged when the most it can cost is higher, or when that cannot be known in advance (GPU-time video and speech models). Video and other long runs return status "running" with a job_id after wait_seconds; poll get_job. A started run always returns its job_id, also when reading its status fails (poll_error): then call get_job later instead of starting it again. Returns { job_id, status, output: { url?, urls?, text?, embedding? }, credits_charged, estimated_credits }; speech audio comes as an audio content block of at most 16 MB (longer texts are refused before the run). Embedding vectors come only in the run's answer (get_job reports their count and dimensions), and lists whose vectors could exceed 16 MB are refused before the run. If reading the charge fails after a run, credits_charged is null and credits_note says so. Transcription (needs a file upload) and categories without an API route (music, 3D, robotics) cannot run here. Without an API key the call returns isError with how to create one (https://railwail.com/en/dashboard/settings/api-keys); the other tools of this server need no key. |
get_jobneeds an API key | job_id | Status and result of a run started by run_model or chat_completion (or through the API), by job_id. Polls the provider for a job that is still running, like GET /api/v1/jobs/{id}, which books the final price or the refund. Needs an API key with the 'jobs' scope or the scope of the job's category, and only answers for jobs of the key's own account. Returns { job_id, status: completed | running | failed, output: { url?, urls?, text? }, credits_charged }. Without an API key the call returns isError with how to create one (https://railwail.com/en/dashboard/settings/api-keys); the other tools of this server need no key. |
get_balanceneeds an API key | — | The prepaid credit balance of the account the API key belongs to: { credits, usd } (1 credit = USD 0.01). Needs an API key with the 'read' scope. Without an API key the call returns isError with how to create one (https://railwail.com/en/dashboard/settings/api-keys); the other tools of this server need no key. |
create_fine_tuning_jobneeds an API key | model, dataset | Fine-tune a robotics model on a public Hugging Face dataset in LeRobot format, like POST /api/v1/fine_tuning/jobs. Before anything is booked the dataset is checked (public, meta/info.json with a codebase_version the model trains on). Credits for the job's GPU time limit are held up front (held_credits, 1 credit = USD 0.01); the GPU time actually used is charged and the rest refunded when the job ends. Trial accounts cannot fine-tune. max_credits refuses the job, before anything is created, when its hold is higher. Returns the job (status queued; a separate training service runs it). Poll get_fine_tuning_job, read list_fine_tuning_events, stop it with cancel_fine_tuning_job. Needs an API key with the 'fine_tuning' scope (https://railwail.com/en/dashboard/settings/api-keys); without one the call returns isError with how to create it. |
get_fine_tuning_job | job_id | Status, hold, charged credits, billed GPU seconds and error of a fine-tuning job of this account, like GET /api/v1/fine_tuning/jobs/{id}. Status: queued, validating, provisioning, running, cancelling, succeeded, failed or cancelled. A succeeded job carries result.download_url, a signed link to the final checkpoint valid for one hour. Needs an API key with the 'fine_tuning' scope (https://railwail.com/en/dashboard/settings/api-keys); without one the call returns isError with how to create it. |
list_fine_tuning_jobs | — | This account's fine-tuning jobs, newest first, like GET /api/v1/fine_tuning/jobs. Page with limit and after (the id of the last job of the previous page); has_more says whether there are more. Needs an API key with the 'fine_tuning' scope (https://railwail.com/en/dashboard/settings/api-keys); without one the call returns isError with how to create it. |
cancel_fine_tuning_jobneeds an API key | job_id | Cancel a fine-tuning job of this account, like POST /api/v1/fine_tuning/jobs/{id}/cancel. A queued job is cancelled at once and its hold refunded in full; a job that is already being trained goes to cancelling, the training service stops it, charges the GPU time used and refunds the rest. Calling it again changes nothing; a finished job cannot be cancelled. Returns the job. Needs an API key with the 'fine_tuning' scope (https://railwail.com/en/dashboard/settings/api-keys); without one the call returns isError with how to create it. |
list_fine_tuning_events | job_id | Events of a fine-tuning job of this account, newest first, like GET /api/v1/fine_tuning/jobs/{id}/events: status changes, training metrics, checkpoints, billing and log lines, each with level, type, message and data. Page with limit and after (an event id). Needs an API key with the 'fine_tuning' scope (https://railwail.com/en/dashboard/settings/api-keys); without one the call returns isError with how to create it. |
Authentication and limits
| Caller | Rate limit | Notes |
|---|---|---|
| No key | 30 requests/min per IP | Plus a shared ceiling of 600 requests/min for all anonymous callers. |
Authorization: Bearer rw_live_… | 300 requests/min per account | Run tools also count against the key's own limit (default 600/min, 60–6,000) and respect its scopes and IP allowlist. |
Every request counts, including tools/list. A key never gives a tool access to another account's data.
Errors
| Code | HTTP | Meaning |
|---|---|---|
-32700 | 400 | Parse error: the body is not JSON. |
-32600 | 400 | Invalid Request: not a JSON-RPC 2.0 message. |
-32600 | 413 | Request body too large: the endpoint accepts at most 256 KB per request. |
-32000 | 429 | Rate limit exceeded. Wait and retry; see the limits above. |
| isError: true | 200 | The tool ran but could not answer (unknown slug, invalid arguments, nothing to price). The text says why. |
Other failures use the standard JSON-RPC 2.0 codes, for example for an unknown method or invalid parameters.
Running models with an API key
With a key, four more tools start real, billed work. They follow the same rules as the REST API: the key's scopes, IP allowlist and rate limit, your monthly spending limit and the same billing.
| Tool | Input | Returns | Key scope |
|---|---|---|---|
chat_completion | model, messages, max_tokens?, temperature?, response_format?, max_credits? | { text, finish_reason, usage, credits_charged, max_price_credits, job_id } | chat |
run_model | model, input, max_credits?, wait_seconds? (0–60, default 30) | { job_id, status: "completed" | "running" | "failed", output: { url?, urls?, text?, embedding? }, credits_charged, estimated_credits, max_price_credits, poll_error? } | scope of the model category: images, video, audio, embeddings or chat |
get_job | job_id | same shape as run_model | jobs, or the scope of the job's category |
get_balance | — | { credits, usd } | read |
create_fine_tuning_job | model, dataset, dataset_revision?, hyperparameters?, suffix?, max_gpu_hours?, max_credits? | fine_tuning.job { id, status, estimated_credits, held_credits, ... } | fine_tuning |
get_fine_tuning_job | job_id | fine_tuning.job | fine_tuning |
list_fine_tuning_jobs | limit?, after? | { data: [fine_tuning.job], has_more } | fine_tuning |
cancel_fine_tuning_job | job_id | fine_tuning.job | fine_tuning |
list_fine_tuning_events | job_id, limit?, after? | { data: [fine_tuning.job.event], has_more } | fine_tuning |
Rules that protect your balance
- max_credits caps the final price: the run is refused before anything is charged when the highest possible price is above it, or when that price cannot be known in advance (GPU-time video and speech models, chat with image, audio or file parts). The answer carries
max_price_credits. Set it for agents that loop. wait_seconds(0–60, default 30): a run that takes longer comes back withstatus: "running"and ajob_id; fetch it later withget_job. A started run always returns itsjob_id: if polling failed (poll_error), callget_joblater instead of starting the run again.- Without a key the run tools answer
isError: truewith a link to the API keys page. New keys have the scopesreadandchat; images, video, audio and embeddings need their scope. - Prices are estimated and held before the run exactly like in the API (1 credit = USD 0.01); failed runs are refunded.
- A key's daily or monthly credit limit applies too: a refused run answers
isError: truewith codeapi_key_limit_exceededandretry_at(when the limit frees up). Nothing was charged, and the tool does not retry; neither should the agent beforeretry_at. Credit limits - With
nabove 1, images whose run failed at the provider come back inerrorswith theirjob_id; they are refunded, the delivered ones are billed. - Transcription (it needs a file upload), music, 3D and robotics models cannot run over MCP; the tool says so instead of guessing. Speech over MCP returns at most 16 MB of audio, so very long texts are refused before the run; use POST /api/v1/audio/speech for them.