Model Context Protocol (MCP)

MCP is a common way for a system to publish tools that any model can call — a ticketing system, a warehouse database, an internal search index. LeafMesh treats those published tools as ordinary tools: you point an agent at a server, and the tools that server offers become part of what that agent's model can do.

There is no separate registration step and no second place to name the same tool. The agent declares the server; the tools follow.

Declaring a server

Add an mcp: block to the agent:

agents:
  - name: research_agent
    agent_type: llm
    model: gpt-4o-mini
    mcp:
      - connection: "search-mcp"   # the record holds the server's URL and token
        name: "search"

The server's address and token are entered only in the vault: make the record under Infrastructure → Integrations → MCP (on 2.4.482 it shows under External agents), and the row names it with connection:. A url or token written inline, including an ${ENV} reference, is refused at load. If the record does not exist yet, the agent is switched off with the reason and starts working as soon as the record exists, with no restart.

That's the whole setup. On start, the SDK asks the server what it offers and builds each tool — name, description, arguments — from what the server reports. research_agent's model now sees those tools alongside its own.

You can edit this in Studio like any other part of the agent. Studio's Tools page (MCP servers) also sets up a server once and picks its record; agents then name it (mcp: [{server: github}]). Adding a server does not require a code change or a redeploy of your agent logic.

A local server

Some servers run as a process rather than a service. Launch it by command:

    mcp:
      - transport: stdio
        command: python
        args: [./servers/inventory.py]
        name: inventory

If the process needs a secret in its environment, put it in the row's env as ${vault:<field>}, so the value comes from the vault, never from the config. This env is the only place a ${vault:} reference is used; everywhere else a block names its record with connection:.

Options

Field	Meaning
`transport`	`http` (default) for a hosted server, `stdio` for one you launch
`connection`	The vault record holding the server's URL and token, for `http`
`command` / `args`	The executable and its arguments, for `stdio`
`use`	Only expose these tools. Leave it out to get everything the server publishes
`name`	Namespace prefix. Derived from the server when unset
`timeout`	Per-call timeout in seconds (default 30)

Taking only what you need

A server may publish thirty tools when your agent needs two. Naming them keeps the agent's tool list short and its choices obvious:

    mcp:
      - connection: "search-mcp"
        use: [search_docs, fetch_page]

How the tools appear

Each tool is prefixed with its server's namespace, so two servers can both publish search without colliding — you get inventory_search and catalogue_search. The prefix comes from the server name, or from name: when you set it.

You do not need to list them under tools:. That list is an allowlist for locally registered tools; MCP tools declared on the agent are merged in automatically. An agent whose only tools are remote can leave tools: out entirely.

Scope and permissions

A server declared on one agent is visible to that agent only. Another agent asking for the same tool is refused, exactly as it would be for a local tool it wasn't granted. There is no shared global pool.

Running alongside your own tools

A remote tool is a tool. In a single turn a model can call an MCP tool and a local one, in parallel or one after another, and each result comes back independently. Remote calls go through the same path as everything else:

the same permission check
the same per-call timeout
the same guardrail around tool output, so a compromised server can't smuggle instructions into the model's reasoning
the same execution record, so the call shows up in the session trace and counts as work in your metrics

Agents pointing at the same server share one connection rather than opening one each, and connections close cleanly on shutdown.

When a server is unavailable

If a server can't be reached at start, the agent still starts — without that server's tools, with a warning in the logs. The rest of the mesh is unaffected. A call that exceeds its timeout returns an error to the model, which can try something else, rather than hanging the session.

Next Steps

Tools Overview — How tools work in LeafMesh
Tool Permissions — Scoping tools to agents
Custom Tools — Writing your own in Python

LeafMesh — someone else's tools, in your agent's hands