---
title: AI Agent Integration (MCP)
description: Use earl templates as tools in AI agents via the Model Context Protocol
icon: Bot
---

Earl supports the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), letting AI agents discover and invoke your API templates as native tools.

## Modes

| Mode          | Behavior                                                                                       |
| ------------- | ---------------------------------------------------------------------------------------------- |
| `--mode full` | Every template becomes a separate tool. Best for small template libraries.                     |
| `--mode discovery` | Exposes only `earl.tool_search` and `earl.tool_call`. Scales to hundreds of templates without consuming context window. |

## Claude Desktop

Add earl to your `claude_desktop_config.json`:

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "earl": {
      "command": "earl",
      "args": ["mcp", "stdio", "--mode", "full", "--yes"]
    }
  }
}
```

If `earl` was installed via `cargo install`, Claude Desktop may not find it on `PATH`. Use the full binary path:

```json
{
  "mcpServers": {
    "earl": {
      "command": "/Users/YOU/.cargo/bin/earl",
      "args": ["mcp", "stdio", "--mode", "full", "--yes"]
    }
  }
}
```

## Claude Code

Add earl as an MCP server in your Claude Code settings (`.claude/settings.json` or `~/.claude/settings.json`):

```json
{
  "mcpServers": {
    "earl": {
      "command": "earl",
      "args": ["mcp", "stdio", "--mode", "discovery", "--yes"]
    }
  }
}
```

Discovery mode is recommended for Claude Code since it keeps the tool list small.

## HTTP Transport

For non-stdio integrations, earl can serve MCP over HTTP:

```bash
earl mcp http --listen 127.0.0.1:8977 --mode full --yes
```

## Write-Mode Safety

Write-mode tools (`annotations.mode: write`) are **blocked by default**. The MCP server must be started with `--yes` to allow them. This prevents agents from performing destructive actions without explicit opt-in.

## Troubleshooting

Run `earl doctor` to validate templates and configuration before starting the MCP server.

Earl logs errors to stderr. To capture logs when running as an MCP server, redirect stderr to a file in your shell before launching, or check your MCP client's server log output.
