MCP Integration

Earl runs as an MCP server, which means your agent can call Earl templates as native tools — no earl call in Bash, no manual flags. This page covers transport options, full vs. discovery mode, the two-session limitation you'll hit the first time, and a few config knobs worth knowing.

Transports

stdio (local agents)

stdio is the right choice when Earl and the agent run on the same machine. The agent spawns Earl as a subprocess; communication goes over stdin/stdout.

Claude Code — add to .claude/settings.json:

{
  "mcpServers": {
    "earl": {
      "command": "earl",
      "args": ["mcp", "stdio"]
    }
  }
}

Same JSON structure for Cursor (.cursor/mcp.json), Windsurf (.windsurf/mcp.json), and Claude Desktop on macOS (~/Library/Application Support/Claude/claude_desktop_config.json).

HTTP (shared/team deployments)

When you want multiple agents or team members pointing at one Earl instance, run the HTTP transport:

earl mcp http --listen 0.0.0.0:8977

HTTP transport requires authentication. Either configure [auth.jwt] in ~/.config/earl/config.toml (see Policy Engine for how JWT auth works), or start it with --allow-unauthenticated if you're on a trusted network and understand what you're accepting.

Full mode vs. discovery mode

Full mode (default)

Every template command becomes one MCP tool. earl call github.search_repos becomes an MCP tool named github.search_repos. The agent sees all tools up front, with their descriptions, and picks the right one.

This works well when you have a small-to-medium number of templates. The agent's context window fills up fast with tool descriptions when you have hundreds.

Discovery mode

Two MCP tools are exposed: earl.tool_search and earl.tool_call. The agent calls earl.tool_search with a natural language description to find relevant templates, then calls earl.tool_call with the exact tool name returned from search.

earl mcp stdio --mode discovery
earl mcp http --listen 0.0.0.0:8977 --mode discovery

Use discovery mode when you have a large template collection and don't want tool descriptions competing for context. The tradeoff: the agent has to know to search before it can call, which adds a round trip. For most workloads with under ~50 commands, full mode is fine.

Calling templates

How an agent calls Earl depends on which mode is running.

Full mode

Templates appear as native MCP tools. earl call github.search_repos becomes an MCP tool named github.search_repos. The agent calls it directly with the declared parameters — nothing special required.

Discovery mode

Two tools are visible. The agent calls earl.tool_search first:

earl.tool_search("find open pull requests on GitHub")

The tool returns a ranked list of matching template names. The agent picks one and calls earl.tool_call:

earl.tool_call("github.list_pull_requests", { "owner": "myorg", "repo": "myrepo", "state": "open" })

CLI fallback

Before MCP is configured, or in the current session after writing the MCP config (see Two-session model below), call Earl through the terminal:

earl call --yes --json provider.command --param value

--yes skips the write-mode confirmation prompt. --json returns structured output instead of the rendered text template. Both flags must come before the command name.

To find available commands:

earl templates list
earl templates search "what you want to do"

The two-session model

This catches everyone the first time. MCP tools do not activate until you restart the agent.

After writing your MCP config, you're still in the same agent session. Earl is not yet a tool source — it activates when the agent starts fresh and reads the updated config. In your current session, use earl call --yes --json through the Bash tool instead:

earl call --yes --json github.search_repos --query "language:rust stars:>100"

After restarting, the templates show up as native MCP tools and you call them directly. Agent-Assisted Setup handles this automatically and tells you when to restart.

Write-mode confirmation

Commands with annotations { mode = "write" } still prompt for confirmation when called through MCP, the same as via CLI. When Earl runs as an MCP server over stdio, the prompt appears as a log message — most agents don't surface MCP log messages to users, which means unattended write calls will hang.

The usual fix is to start the MCP server with --yes:

earl mcp stdio --yes

That pre-approves all write calls for the session. Use it carefully — you're saying "approve everything" rather than reviewing each write. For multi-user HTTP deployments, use the policy engine to set per-caller write access instead of relying on --yes. See Policy Engine.

Checking what's available

Use earl templates list to see what commands are loaded before connecting an agent:

earl templates list

This shows all available commands with their modes and summaries — the same set that would appear as MCP tools in full mode.