MCP Servers

Model Context Protocol is a standard for exposing tools to LLMs. Once you point an agent at an MCP server, the agent sees its tool catalogue and can invoke tools mid-conversation — look up an order, fetch a product, file a ticket, search a database. The LLM decides; the platform executes; the result feeds back into the reply. All in a single /v1/chat call.

• stdio (local process)Spawns an MCP server as a local subprocess on the platform's runner and talks to it over stdin/stdout. Best for first-party tools that ship as a CLI binary — filesystem, shell, git wrappers. Requires command + args + optional env.
• SSE (Server-Sent Events)Connects to a remote HTTP endpoint that streams events. Best for legacy MCP servers or when you want the server lifetime decoupled from request lifetime. Requires a URL like https://mcp.example.com/sse and optional headers.
• HTTP (streamable)The newer, recommended remote transport. A single request/response endpoint that supports chunked streaming. Best for production deployments — easier to host, friendlier to firewalls. Requires a URL like https://mcp.example.com/mcp.

• NameShort identifier shown in the agent's tools list and in Tracing. Make it human (orders-api, not srv-7). Unique per agent.
• TransportPicks which connection mode to use. Switching transport reveals/hides the relevant fields below.
• Command + Arguments (stdio)The binary to spawn and its args. npx is the most common command for first-party@modelcontextprotocol/server-* packages.
• Environment (stdio)One KEY=value per line. Injected into the spawned process. Use this for provider keys the local server needs — never put secrets in Arguments where they'd show up in process listings.
• URL (sse / http)Fully-qualified endpoint. SSE wants the streaming path (usually /sse); HTTP wants the MCP root (usually /mcp).
• Headers (sse / http)Custom request headers, one Header-Name=value per line. Useful for tenant scoping, version pinning, or upstream gateway routing.
• Auth schemeBearer sends Authorization: Bearer <token>; API key sends a custom header (you name it); Basic sends username + password as RFC 7617; None sends nothing.
• Test connectionHits the server, lists its tools, and shows the round-trip latency. Catch misconfig before saving.

Diagnostics break the connection into discrete steps so you can pinpoint failures. A 401 at the handshake step is auth; a timeout at DNS is a domain typo or a private DNS issue; a slow tool list (>2s) usually means the server is doing heavy work on startup.

Each request, the platform builds the tool catalogue from every enabled MCP server attached to the agent and gives it to the LLM. When the LLM asks to call a tool, the platform routes the call to the right server, captures the result, and feeds it back to the LLM. This loop runs up to max_tool_rounds (default 8) before the final reply is returned.

The full sequence — which tool was called, the input the model sent, the output the tool returned, per-step latency — is visible in Tracing. That's the right place to debug "why did/didn't the agent call my tool?".

// Response shape when a tool fires
{
  "conversation_id": "conv-…",
  "message": { "role": "assistant", "content": "Order ORD-1234 ships Friday via FedEx." },
  "tool_calls": [
    {
      "name": "get_order",
      "input": { "order_id": "ORD-1234" },
      "output": "{\"status\":\"shipped\",\"carrier\":\"FedEx\",\"eta\":\"2026-04-07\"}"
    }
  ]
}