Back to docs

MCP servers

Zod includes a minimal Model Context Protocol (MCP) client over HTTP. Declare an MCP server in Settings → MCP, and its tools are surfaced to the agent loop alongside built-ins and custom tools.

What is MCP?

MCP (Model Context Protocol) is a standard way to expose external tools and data to an AI agent. Instead of wiring each integration by hand, you point Zod at an MCP server over HTTP — the server advertises its tools, and Zod executes them on call, all from the browser.

Configuring a server

MCP servers are declared as YAML in Settings → MCP. Each server is a name, an HTTP url, and optional headers:

mcpServers:
  - name    : weather
    url     : http://localhost:8000/mcp
    headers :
      Authorization: Bearer sk-test-1234

How the client works

The built-in MCP-over-HTTP client speaks JSON-RPC 2.0. On connect it performs the standard handshake, then lists and calls tools:

POST /mcp

initialize                → server responds with capabilities & protocol
notifications.initialized → notify the server the session is ready
tools/list                → returns the server's available tools
tools/call                → invokes a tool with arguments
  • The client tracks the Mcp-Session-Id header returned by the server and sends it on subsequent requests.
  • Responses are parsed from both plain JSON and SSE (server-sent events) streams.
  • Custom headers are sent with every request, so authenticated servers work out of the box.

Tools in the loop

Each connected server's tools are appended to the schemas offered to the model in the agent loop. When the model calls one, it is dispatched through the shared runAnyTool (custom → MCP → built-in), so MCP tools work identically in chat, the scheduler, and agent steps. Connected MCP tools are refreshed automatically on init and on save.

Connecting

To test, point Zod at any MCP server that speaks JSON-RPC over HTTP. For example, a local mock server:

mcpServers:
  - name    : mock-tools
    url     : http://localhost:8000/mcp

Once saved, the server's tools appear in the loop automatically. Keep the server running and make sure its URL is reachable from your browser.