Replicate's MCP server maps its HTTP API almost one to one, so the usual coverage gap is missing. What differs is control: async prediction handling, webhook delivery, output persistence and retries are things your code has to own, and an MCP tool call is a poor place to own them. Both paths also run on the same credential, an API token that spends the account's credit. This guide compares what each path lets an agent do, who holds the token on each, and how to run a generation pipeline for many customers in production.
Your agent needs to run models: generate an image, transcribe a file, upscale a frame, fine-tune on a customer's data. Replicate hosts those models behind one HTTP API, and it also ships a Model Context Protocol (MCP) server that exposes the same API as tools. From a demo, they look identical. In production they diverge on how async work is handled, who stores the token, and how much spend one leaked credential can authorize. Here's how to pick.
Replicate publishes two MCP servers built on its OpenAPI spec with Stainless. The local server is the replicate-mcp npm package, released in July 2025 and started with npx -y replicate-mcp. It reads REPLICATE_API_TOKEN from the client config and runs over stdio. The remote server at https://mcp.replicate.com launched on August 10, 2025. It runs on Cloudflare Workers, uses Cloudflare's OAuth Provider Framework for the client handshake, and asks the user to paste a Replicate API token into a web page; the token is stored in Cloudflare KV and never exposed to the AI tool. Replicate recommends the remote server for most users.
Large JSON responses are trimmed with a WebAssembly build of jq, and the model writes the filter expression. An experimental code mode (--tools=code) replaces the endpoint tools with a docs search tool and a TypeScript executor that runs the Replicate SDK in a local Deno sandbox. Since February 10, 2026, the server is discoverable through the official MCP Registry via /.well-known/mcp/server.json. Docs: Replicate MCP reference and the remote MCP launch post.
The HTTP API at https://api.replicate.com/v1 covers predictions (create, get, list, cancel), models (including search, readme, examples, and official-model predictions), model versions, collections, deployments and deployment predictions, trainings, hardware, account, files, the beta search endpoint, and the default webhook signing secret. Auth is a single header, Authorization: Bearer <token>, using a token from replicate.com/account/api-tokens. Docs: Replicate HTTP API reference.
The pattern here is different from most MCP comparisons. Replicate's MCP server is generated from the same OpenAPI spec as the API, so the endpoint coverage is close to identical. What MCP cannot give you is the asynchronous plumbing around a prediction: webhooks need a receiving endpoint, outputs need to be copied somewhere durable, and retries need state. Those live in your code, not in a tool call.
The model gets every endpoint with a schema it already understands, and code mode lets it chain calls in TypeScript instead of round-tripping through the context window. For exploration, that is a real advantage: "find an image upscaler, read its inputs, and run it on this file" works without writing a single tool definition.
On the API side, you write that layer. Every Replicate model has its own input schema under openapi_schema.components.schemas.Input on its version object, and an agent needs a tool description good enough to tell the model to read that schema first. Writing the schema is the hard part. Not the API call.
On the remote MCP path, the MCP client completes a handshake with the Cloudflare Workers OAuth provider at mcp.replicate.com, and the user pastes a Replicate API token into a web page during that flow. The token is stored in Cloudflare KV, and the server calls Replicate with it. The OAuth layer authenticates the client to Replicate's MCP server; it does not issue a scoped, user-consented grant against Replicate's API. Underneath, it is still the full API token.
On the local MCP path, the token sits in REPLICATE_API_TOKEN inside a JSON config file on the machine running the client. That is fine on a developer laptop. It is not an option for a product serving many users.
On the direct API path, your code sends Authorization: Bearer <token> on every request. Replicate's HTTP reference documents no token scopes, and tokens belong to a user or an organization. A token that can run a prediction can also create a deployment with min_instances above zero, start a training, or delete a model.
That last point is what changes the blast radius. A Replicate token is a spend credential. Replicate's own rate-limit docs tie throttling to credit balance, which tells you where the risk sits: a leaked token is not just data exposure, it is compute billed to your customer. What the user can't do, the agent can't do; on Replicate, what the token can do is everything the account can pay for.
In a multi-tenant B2B agent, MCP's flow gives you a token per user. Direct API calls give you a credential per user. In neither case does the path itself solve storage, rotation, or revocation; those are infrastructure problems regardless of which path you choose.
Replicate adds a specific wrinkle: the token determines who pays. If your agent runs predictions on a customer's behalf with your own platform token, you have merged every customer's spend into one account and lost the ability to attribute it. If you run with each customer's token, you need to bind each one to exactly one user or organization, because replicate_get_account will happily tell you whose token it is only after you have already used it.
Recommended reading: OAuth vs API keys for AI agents
On the MCP path, Replicate owns the tool schemas, the jq filtering, and keeping the remote server current with the API. You still own the token store for every user, the reconnect experience when a user revokes a token, and the cost of long-running predictions blocking a chat turn while the model polls. Tool names come from the generator (create_predictions, get_models_versions), and Replicate notes the hosted server is "automatically updated," so the tool surface can shift without a release on your side.
On the API path, you own everything. The published limits are 600 requests per minute for creating predictions and 3,000 requests per minute for every other endpoint, with short bursts allowed. Throttled calls return 429 with a message such as "Request was throttled. Your rate limit resets in ~30s." Accounts with granted credit and no payment method are capped at 1 request per second and 6 per minute, a limit that surprises teams testing with trial credit.
Prefer: wait=n holds the request open for up to 60 seconds. If the model is slower, you get the prediction back in starting or processing and must poll predictions.get or rely on a webhook. Predictions and trainings lists page at 100 records with next and previous cursors. Output files are served from replicate.delivery and require the Authorization header to download, and for API-created predictions, inputs, outputs, and logs are deleted after one hour, leaving output as null and data_removed as true.
Webhooks are signed with HMAC-SHA256 using webhook-id, webhook-timestamp, and webhook-signature headers over ${webhook_id}.${webhook_timestamp}.${body}. The signing secret comes from GET /v1/webhooks/default/secret and is per user or per organization. In a multi-tenant system, that means a verification key per connected account, not one global secret.
Use Replicate MCP when:
Use the Replicate API when:
Both paths hand you a credential per user. Neither hands you a vault. In a multi-tenant agent, 50 customers with 4 Replicate users each is 200 API tokens. Each one must be stored encrypted, bound to its user and the Replicate account it bills, replaced when a user rotates it at replicate.com/account/api-tokens, and removed when an employee leaves or a customer churns.
The token type does not even change between paths: it is a Replicate API token whether it sits in Cloudflare KV behind mcp.replicate.com, in an .env file, or in your database. What changes is who holds it. With the hosted MCP server, Replicate holds it per MCP client session, which you do not control from a multi-tenant backend. With the API, you hold it, and every token is a key to someone's compute budget.
Scalekit's Replicate connector stores each user's Replicate token in the token vault and sends it with every call, so the MCP vs API decision doesn't change your auth infrastructure. Your agent passes an identifier; the token never enters the agent runtime or the LLM context.
Recommended reading: why a token vault matters for AI agent workflows
Scalekit's replicate connector is an API-path connector with 33 tools (19 read, 10 write, 4 destructive). It authenticates with an access token: each user enters their own Replicate API token once through a Scalekit-hosted page, and Scalekit stores it as that user's connected account credential.
Create a Replicate connection in AgentKit > Connections in the Scalekit dashboard. The name you give it is the connection_name your code passes, and the string must match the dashboard exactly. This is the most common integration error. Copy SCALEKIT_ENVIRONMENT_URL, SCALEKIT_CLIENT_ID, and SCALEKIT_CLIENT_SECRET from Developers > API Credentials into .env.
get_or_create_connected_account returns the user's connected account. If it is not ACTIVE, get_authorization_link returns a link to the page where the user enters their Replicate API token. The agent never sees the token.
This is not a catalog load. The agent asks for the tools this user's connected account is authorized to call, and narrows them to the five a generation agent needs. Loading all 33 Replicate tools would put replicate_create_deployment, replicate_create_training, and replicate_delete_model in front of a model that should only be running predictions, and each of those can spend money or destroy work.
The loop runs until the model stops requesting tools. Every call executes with this user's Replicate token, so every prediction bills to their account.
For pipelines, skip the model. execute_tool runs one tool with a fixed input and returns data plus an execution_id you can log. Pass a webhook so completion drives your pipeline instead of polling, and verify the signature on receipt.
Copy outputs to your own storage when the prediction reaches succeeded. Replicate deletes API prediction data after one hour.
Scalekit does not ship a connector for Replicate's MCP endpoint, and the prebuilt tools do not cover file uploads or the webhook signing secret. If you need those endpoints, register a custom connector and make proxied calls through actions.request(), keeping the same connected account and vault model.
The replicate connector has 33 tools. At roughly 200 tokens per tool definition, that is about 6,600 tokens of context before the agent does any work, and the model is choosing from a decision space that includes deployment scaling, training, and deletion. The fix is not better prompting. It is surface reduction. A Scalekit virtual MCP server declares exactly which tools an agent role can see, and session tokens keep each run bound to one user's connected accounts. Docs: set up a virtual MCP server.
One server definition serves every user. Before each run, check that the user's accounts are active and mint a short-lived session token scoped to them. Any MCP client that speaks streamable HTTP can connect; this example uses langchain-mcp-adapters (pip install langchain-mcp-adapters) and passes the token as a Bearer header.
The agent sees three tools. It can run a model and report the result; it cannot scale a deployment or start a training. The endpoint is static; the identity is per-user.
Every execute_tool call returns an execution_id, and every execution is attributed to a connected account, which maps to one of your users and one customer tenant. When a customer asks why their Replicate bill doubled last Tuesday, or which agent run created a deployment that never scaled to zero, the answer is a lookup, not an investigation.
A shared platform token breaks this. Replicate sees one account making every prediction, and your side of the audit trail can only prove that the platform token did it. Shared credentials are a single-user solution. They do not survive a second user.
Recommended reading: audit trails for agent auth
If your agent is an interactive assistant in Claude, Cursor, or VS Code where a user explores models, reads their inputs, and runs quick predictions while they wait, use Replicate MCP. The generated tools and code mode cover the whole API with no schema work. If your agent runs headless, depends on webhooks, must persist outputs past the one-hour window, or needs to stay predictable against the 600 per minute prediction limit, use the API directly.
Either way, the credential problem is the same, and that's what needs production-grade infrastructure. On Replicate, the stakes are sharper than usual: there are no scopes to narrow a token, so the only least-privilege controls you have are which user's token runs the call and which tools the agent can see. Get both right before the first customer connects.
Yes, two, both generated from its OpenAPI spec. The local server is an npm package started with one command that reads the API token from the client config. The remote server launched in August 2025, runs on Cloudflare Workers, and asks the user to paste a Replicate API token into a web page during the client handshake; Replicate recommends it for most users. An experimental code mode replaces endpoint tools with a TypeScript executor.
Coverage is close to identical, 35 per-endpoint tools against the same predictions, models, deployments, trainings, files and webhook endpoints. The difference is the asynchronous plumbing: webhooks need a receiving endpoint an MCP client does not have, outputs need to be copied to durable storage before Replicate deletes them, and retries need state. Those live in your code, not in a tool call.
No. Replicate's HTTP reference documents no token scopes, and tokens belong to a user or an organization. A token that can run a prediction can also create a deployment with minimum instances above zero, start a training, or delete a model, and everything it does is billed to the account. The only least-privilege controls are which user's token runs the call and which tools the agent can see.
For predictions created through the API, inputs, outputs and logs are deleted after one hour, leaving the output empty and a flag showing the data was removed. Output files are served from Replicate's delivery domain and require the authorization header to download. A production pipeline copies each output to its own storage as soon as the prediction succeeds.
When it runs headless, such as a background job that transcribes every uploaded recording or generates product images for a catalog import; when signed webhooks should drive the next step instead of a model polling in a loop; when outputs must outlive the one-hour window; or when it must stay under 600 prediction creates per minute and route steady traffic through a deployment with controlled instance counts.
The Replicate connector exposes 33 tools over the HTTP API. Each user enters their own Replicate token once through a hosted page, Scalekit stores it in the token vault and sends it with every call, a virtual MCP server narrows a generation agent to running predictions so it cannot scale a deployment or start a training, and every execution is attributed to the user whose account it bills.
Browse the Scalekit Replicate connector and the Replicate connector docs with the full tool list. See Scalekit pricing, or talk to us.
