MCP & Tools

Two ways to give agents capabilities

MCP servers

Remote servers you connect by URL. Tools are discovered automatically at startup. The server can be in any language.

Python tools

Local Python functions. You write the implementation; the engine binds them to agents that declare them.

From the agent’s (and the LLM’s) perspective, both look identical — they’re just tools the model can call. By default, both local and MCP tool calls pause for human approval before they run. See Human-in-the-Loop to configure approval behavior and auto mode.

MCP servers

Declare a server by URL. The engine connects and discovers its tools automatically at startup.

mcps:
  orders_mcp:
    url: "https://api.acme.com/mcp"

  catalog_mcp:
    url: "https://catalog.acme.com/mcp"

Then give agents access to the servers they need:

agents:
  orders_agent:
    description: "Handles order questions."
    mcps: [orders_mcp]

  catalog_agent:
    description: "Answers product questions."
    mcps: [catalog_mcp]

Each agent only sees the MCP tools from its own declared servers.

MCP connections are created once at startup, not per request. If a server is unreachable, the engine logs a warning and continues — local tools still work.

Tool tags

If your MCP server groups tools into categories, you can limit which tools an agent sees:

mcps:
  crm_mcp:
    url: "https://crm.acme.com/mcp"
    tool_tags: ["read-only"]       # only discover tools tagged "read-only"

Tags are sent as the X-MCP-Tool-Tag header during tool discovery. The server filters — the engine binds only what comes back. The LLM never sees the tags. Multiple tags are sent comma-joined: X-MCP-Tool-Tag: orders,returns Custom transport — if your server expects a different header or a query param, tool_tag_transport supports two types:

`type`	Where the tag goes	Required field
`header`	A custom request header	`header_name`
`query_param`	A query string parameter on the MCP `url`	`param_name`

mcps:
  legacy_api:
    url: "https://legacy.acme.com/mcp"
    tool_tags: ["v2"]
    tool_tag_transport:
      type: query_param
      param_name: "tag"
      # result: ?tag=v2 appended to the URL

mcps:
  internal_api:
    url: "https://internal.acme.com/mcp"
    tool_tags: ["support"]
    tool_tag_transport:
      type: header
      header_name: "X-Api-Group"

MCP auth

To add auth headers to outgoing MCP requests, use a before_mcp_request hook. The token never appears in the YAML or in prompts. See Runtime Hooks.

Python tools

Declare a tool with a description. That description is what the LLM uses to decide whether to call it.

tools:
  get_order_status:
    description: "Get the current status and tracking info for an order. Requires an order ID."

  create_return:
    description: "Open a return request for a delivered order. Requires order ID and reason."

  send_notification:
    description: "Send an email or SMS notification to the customer."

Agents declare which tools they have access to:

agents:
  orders_agent:
    tools: [get_order_status]

  returns_agent:
    tools: [create_return, send_notification]

An agent can only call tools it explicitly declares. The engine enforces this — the model cannot reach a tool that isn’t in its list.

Implementing a tool

Run generate (see Quickstart) to create stubs. Then fill in the logic:

# plugins/tools/get_order_status.py

def get_order_status(order_id: str) -> dict:
    """Get the current status and tracking info for an order. Requires an order ID."""
    # your business logic here
    return {
        "status": "shipped",
        "tracking_number": "1Z999AA10123456784",
        "estimated_delivery": "2026-07-05"
    }

The docstring becomes the tool description the LLM sees. The engine wraps the function automatically.

Write clear descriptions and typed parameters. The LLM reads both when deciding how to call a tool. Vague descriptions lead to wrong or missed tool calls.

Calling a real system as the user

A tool that reaches your own API should act as the person who asked, so your API applies their permissions. The credential the request arrived with is on the run context — not a parameter, since anything in the signature becomes part of the schema the LLM sees:

from agent_engine.runtime.hooks import current_run_context

def get_order_status(order_id: str) -> dict:
    """Get the current status and tracking info for an order. Requires an order ID."""
    ctx = current_run_context.get()
    auth = ctx.auth_context if ctx else None
    if auth is None or not auth.inbound_access_token:
        return {"error": "No credential for this request; the user must sign in."}
    return your_api.get(order_id, token=auth.inbound_access_token)

It is filled from the caller’s Authorization header (see Identity), and never reaches the model.

When there is no credential, fail. A fallback to one shared admin key lets every caller do whatever that key can.

Resolvers vs. tools

Both are Python code. The difference is when they run and who calls them.

	Resolver	Tool
Called by	Engine (always, before the node runs)	LLM (when it decides to)
Visible to LLM	No	Yes (name + description)
Token cost	None	Yes
Purpose	Fill `{{variables}}` in prompts	Perform actions on request

Use a resolver for context the prompt always needs: current date, user name, account info. Use a tool for actions the user may or may not need: look up an order, create a return, send a message.

Tool call tracing

Every tool call is tracked in the run result — agent, tool name, provider (local or MCP), success or failure, latency. You can see this in logs and in Langfuse if tracing is enabled.

tools used:
  * get_order_status [local] succeeded (42ms)
  * crm_lookup [mcp: crm_mcp] succeeded (118ms)

Shared tool usage across agents

Tool usage is stored in a repository, not carried in graph state, so every agent and orchestrator working on the same conversation shares it. Each one is privately told what has already been run — including in earlier turns of the same conversation, so an agent can answer “which tools have you used?”:

## Execution record for this conversation

### Tools executed
user_management:
- create_user [succeeded]

### Agents delegated to
- openwebui -> admin_management

Tools and agents are listed apart on purpose: an orchestrator’s children are bound to it as tools, so a flat list made it answer “the tool I ran is admin_management” when it had only routed there. For direct questions (“which tools have you run?”), orchestrators also get a read-only list_executed_tools tool that returns the executed tools straight from the repository. The passive context is useful for reasoning but a model can still mistake a bound child agent for a tool when explicitly reporting. This deterministic lookup trades one reserved engine-tool name and an extra model tool call for an answer grounded in repository data. It is not recorded, does not consume tool/child-call limits, and a configured child with the same name wins. That block is internal execution context: it is given to the model as a system message, never as a conversation turn, and never persisted as chat history. Only agent, tool name, and status are included — never arguments, results, or errors. It is refreshed before every model turn, so a supervisor’s final answer reflects what the agents it just called actually ran. The store behind it is a repository port. The in-memory adapter ships with the engine; a shared backend (Redis, PostgreSQL) is an adapter swap in the composition layer, with no change to agents or tools. Bounded reads return the newest matching records in chronological order, and context requests one extra record only to detect truncation.

Get Started

Core Concepts

Features

Widget

Reference

Two ways to give agents capabilities

MCP servers

Python tools

MCP servers

Tool tags

MCP auth

Python tools

Implementing a tool

Calling a real system as the user

Resolvers vs. tools

Tool call tracing

Shared tool usage across agents

​Two ways to give agents capabilities

MCP servers

Python tools

​MCP servers

​Tool tags

​MCP auth

​Python tools

​Implementing a tool

​Calling a real system as the user

​Resolvers vs. tools

​Tool call tracing

​Shared tool usage across agents

Two ways to give agents capabilities

MCP servers

Tool tags

MCP auth

Python tools

Implementing a tool

Calling a real system as the user

Resolvers vs. tools

Tool call tracing

Shared tool usage across agents