MCP Tools

Agent One uses the Model Context Protocol (MCP) for tool execution. MCP is a JSON-RPC protocol over stdio that lets the agent discover and call tools from external servers. Adding a new capability is 4 lines of config — no code changes.

How MCP Works

Agent One ←── JSON-RPC over stdio ──→ MCP Server (any language)
    │                                       │
    ├── tools/list (discover tools)         ├── Exposes tools with JSON Schema
    ├── tools/call (execute tool)           └── Returns results as text
    └── Summarizes results for LLM

1. Agent One spawns the MCP server as a subprocess
2. On startup, it calls tools/list to discover available tools
3. The LLM sees tool names, descriptions, and input schemas
4. When the LLM decides to call a tool, Agent One sends tools/call via JSON-RPC
5. The result is summarized and added to the conversation context

Adding an MCP Server

Add 4 lines to your config.yaml:

tools:
  mcp_servers:
    - name: github
      command: "npx"
      args: ["-y", "@anthropic/github-mcp"]
      env:
        GITHUB_TOKEN: "${GITHUB_TOKEN}"

That’s it. On next startup, Agent One discovers all tools the GitHub MCP server exposes and makes them available to the LLM.

Common MCP Servers

tools:
  mcp_servers:
    # ClickUp — task management
    - name: clickup
      command: "npx"
      args: ["-y", "@anthropic/clickup-mcp"]
      env:
        CLICKUP_API_KEY: "${CLICKUP_API_KEY}"

    # GitHub — repos, PRs, issues
    - name: github
      command: "npx"
      args: ["-y", "@anthropic/github-mcp"]
      env:
        GITHUB_TOKEN: "${GITHUB_TOKEN}"

    # Engram — long-term memory
    - name: engram
      command: "engram"
      args: []

    # Playwright — browser automation
    - name: playwright
      command: "npx"
      args: ["-y", "@anthropic/playwright-mcp"]

Tip

Check MCP server directory for available servers. Any server that speaks the MCP protocol works with Agent One.

Built-in Tools

Agent One includes a few built-in tools that don’t require external MCP servers:

Purchases

Track personal purchases with automatic categorization.

tools:
  builtin:
    purchases:
      enabled: true
      backup_to_clickup: true
      clickup_folder: "Personal/Purchases"

Usage via chat:

> Track purchase: headphones $120
> How much did I spend this month?
> Show purchases over $50 from last week

Reminders

Set time-based reminders that fire as signals.

tools:
  builtin:
    reminders:
      enabled: true

Usage via chat:

> Remind me to call the dentist tomorrow at 3pm
> What reminders do I have pending?

Config Mutator

Modify the agent’s own configuration via chat. Always enabled.

> Change the Monday report to Tuesday 9am
> Add a new MCP server for Google Calendar
> Disable the heartbeat

Members

Manage team members (owner-only tool).

> Add Maria as an admin
> List all team members
> Change Juan's role to member

Portal

Generate access links for the web portal.

> Generate a portal access link for Maria

Tool Result Handling

Tool results are summarized before adding to the LLM context. If a ClickUp query returns 50 tasks, the agent sees a summary of the top 5 most relevant ones. This keeps token usage low.

The summarization strategy:

1. Tool returns raw result (could be large JSON)
2. Agent One truncates or summarizes based on result size
3. Only the summary enters the conversation context
4. Full results are available in the audit log

Tool Call Safety

Timeout

All tool calls execute with a context timeout. If a tool hangs, it’s killed and the agent reports the timeout.

Loop Guard

The agent detects repeated identical tool calls (same name + same arguments via SHA256 hash). After 3 identical calls in a row, the circuit breaker fires and the agent moves on. This prevents runaway loops from LLM hallucination.

Budget

Tool calls consume tokens (the LLM processes the result). The budget tracker accounts for this. When budget is low, the agent uses the cheap model and may skip non-essential tool calls.

MCP Server Lifecycle

MCP servers follow a pipeline lifecycle:

1. Spawn — start the subprocess
2. Initialize — handshake and capability discovery
3. Ready — tools available for use
4. Shutdown — graceful termination on agent exit

If a server crashes, Agent One logs the error and continues without that server’s tools. It doesn’t crash the entire agent.