Guides

Serve agents over MCP

By the end of this page your registered agents will appear as tools inside Claude Desktop and Cursor, and you will know how to host the same server as a remote HTTP endpoint — standalone or embedded in an existing FastAPI app.

The Model Context Protocol (MCP) is the wire format clients like Claude Desktop use to discover and call external tools. The core idea of this page: every registered agent becomes an MCP tool. The server walks the agent registry at startup, turns each AgentMetadata record into a tool definition (the safe_name becomes the tool name, the description and input_schema travel with it), and also exposes a models://list resource that returns every agent with its model path, tags, and live routing statistics. Two default agents ship pre-registered so the server is never empty: llama3_chat (meta/meta-llama-3-70b-instruct) and flux_pro (black-forest-labs/flux-1.1-pro).

Steps

1. 1

   Run the server over stdio

   The default transport — the client launches the process and talks over stdin/stdout.

2. 2

   Register with Claude Desktop and Cursor

   One JSON entry tells the client how to launch replicate-mcp-server and which env vars to pass.

3. 3

   Host it remotely over HTTP

   --transport sse or streamable-http turns the same server into a network endpoint.

4. 4

   Load workflows at startup

   --workflows-file registers declarative YAML workflows before the server accepts connections.

1. Run the server over stdio

Stdio is the right transport for desktop clients: the client owns the process lifecycle, so there is no port, no daemon, and nothing to clean up. Run it once by hand to confirm it starts:

replicate-agent serve --transport stdio

Starting MCP server (stdio)…

--transport stdio is the default, so plain replicate-agent serve does the same thing. If you instead see ⚠ REPLICATE_API_TOKEN is not set. Tool calls will fail until it is exported., the server still starts — discovery works, but every tool call will return an error until the token is present. The process now waits for a client on stdin; press Ctrl+C to exit. The package also installs a second executable, replicate-mcp-server, which is the stdio entrypoint without the CLI wrapper — that is the one desktop clients launch in the next step.

2. Register with Claude Desktop

Add this entry to ~/.config/claude/mcp_config.json (create the file if it does not exist):

{
  "mcpServers": {
    "replicate-agent": {
      "command": "poetry",
      "args": ["run", "replicate-mcp-server"],
      "env": {
        "REPLICATE_API_TOKEN": "${REPLICATE_API_TOKEN}"
      }
    }
  }
}

The example uses poetry run for a source checkout; if you installed from PyPI into a plain virtualenv, set command to the absolute path of the replicate-mcp-server script instead. Restart Claude Desktop and open the tool palette — you should see llama3_chat and flux_pro listed, plus any agents your own modules register.

Cursor uses the same server definition. Point Cursor's MCP settings at the identical command/args/env trio; the protocol and the executable are unchanged, only the location of the config differs by client.

3. Host it remotely over HTTP

For a shared or cloud-hosted endpoint, switch the transport. sse serves the established Server-Sent Events transport; streamable-http is the modern MCP 1.x successor with bidirectional streaming over a single connection. Both require uvicorn (pip install uvicorn).

replicate-agent serve --transport sse --host 0.0.0.0 --port 8080

Starting MCP SSE server on http://0.0.0.0:8080
INFO:     Started server process [4242]
INFO:     Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)

The defaults are --host 0.0.0.0 and --port 8080; add --mount-path to prefix the SSE endpoint URL and --log-level info to tune uvicorn's verbosity. For Streamable HTTP, the shape is the same: replicate-agent serve --transport streamable-http --host 0.0.0.0 --port 9090. The same three deployments exist as Python entry points in replicate_mcp.server — serve_http(host, port, mount_path, log_level) for SSE, serve_streamable_http(host, port, log_level), and get_asgi_app() when you want the ASGI application object instead of a running process:

from fastapi import FastAPI
from replicate_mcp.server import get_asgi_app

app = FastAPI()
mcp_app = get_asgi_app(transport="sse", mount_path="/mcp")
app.mount("/mcp", mcp_app)

4. Load workflows at startup

If you have declarative workflows in YAML (covered in Agents & workflows), pass the file at serve time and they are registered before the first client connects:

replicate-agent serve --transport sse --workflows-file workflows.yaml

✓ Loaded 2 workflow(s) from workflows.yaml
Starting MCP SSE server on http://0.0.0.0:8080

Verification

Common mistakes

Next steps

• Agents & workflows — register your own agents so they show up as MCP tools, and compose them into pipelines.
• CLI reference — every serve flag, plus the agents, workflows, and audit sub-commands.
• Distributed execution — scale beyond one host with worker nodes and a coordinator.