Skip to main content
Glama
sena-labs

Replicate-MCP-Server

by sena-labs
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Start Async Batch Predictions

replicate_batch_start

Start 2–50 Replicate predictions in parallel as a background job and get a job_id immediately; poll batch status for progress and results.

Instructions

Run multiple Replicate predictions in parallel as a background job. Returns a job_id immediately — the predictions run in the background. Poll replicate_batch_status for progress and results.

Use this when you have 2–50 predictions to run and don't want to block. Each item specifies its own model and input, so you can mix models in one batch.

IMPORTANT: model must be a full Replicate identifier ("owner/name" or "owner/name:version"), not a curated shortcut like "flux-schnell". Use replicate_get_model_schema to look up the correct identifier.

Args:

  • items (array, 1–50): Predictions to run. Each: { model: "owner/name[:version]", input: {...} }.

  • concurrency (1–10, default 3): Max simultaneous predictions. Raise with caution — Replicate rate-limits free accounts.

  • download (boolean, default true): Download output files locally.

  • timeout_ms_per_item (default 300000): Per-prediction timeout. Timed-out items have pending=true in their result.

  • ttl_hours (1–72, default 1): How long to keep results in memory. Job state is lost if the MCP server restarts.

Returns: { job_id, total, message }

Example: items=[ { model: "black-forest-labs/flux-schnell", input: { prompt: "a red fox" } }, { model: "black-forest-labs/flux-schnell", input: { prompt: "a blue whale" } }, ] → Returns { job_id: "abc-123", total: 2, message: "..." } → Then poll: replicate_batch_status({ job_id: "abc-123" })

Input Schema

NameRequiredDescriptionDefault
itemsYesPredictions to run. 1–50 items.
downloadNoDownload output files locally. Default: true.
ttl_hoursNoHow long to keep job results in memory (1–72h). Default: 1h. State is lost if the server restarts.
concurrencyNoMax simultaneous predictions (1–10). Default: 3.
timeout_ms_per_itemNoPer-prediction timeout in ms (5000–1800000). Default: 300000 (5min).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv3.3.1
    • addedInput schema / properties / items / items / properties / input / propertyNames
      Added value: +{
+  "type": "string"
+}
  2. First observedv3.2.3

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only say non-readonly, open-world, non-idempotent, non-destructive; the description adds substantially more: fire-and-forget async semantics, state loss on MCP server restart, TTL-bounded result retention, rate limiting on free accounts when concurrency is raised, and that timed-out items come back with pending=true. These are exactly the operational risks an annotation cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core contract, then constraints, then a concrete worked example that demonstrates mixing models in one batch and the poll handoff. Slightly redundant with the 100%-covered schema in the Args block, but the ordering and the example justify the length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, yet the description supplies the return shape ({ job_id, total, message }), the polling follow-up, the durability caveat, and the failure mode for slow items. For a 5-parameter async job starter there is nothing material an agent needs that is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description earns one above it by adding judgment the schema lacks — the caution that concurrency should be raised carefully due to Replicate free-tier rate limits, and the consequence of timeout_ms_per_item (pending=true in results). It restates bounds that the schema already enforces (1–10, 1–72) rather than going further, which keeps it from a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Run multiple Replicate predictions in parallel as a background job") and immediately establishes the async contract (returns job_id, runs in background). It clearly separates itself from replicate_run_model (single, blocking) and replicate_batch_status (polling), so an agent can choose correctly without reading the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Use this when you have 2–50 predictions to run and don't want to block" gives both the condition and the implicit exclusion (fewer than 2 / blocking calls belong elsewhere). It routes the agent forward to replicate_batch_status for results and to replicate_get_model_schema for identifier lookup, closing the two follow-up questions an agent would otherwise have.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools