Set up the MCP server

Loggerhead ships an MCP server inside the Mac app. An AI coding tool starts it, and the server reads logs, metrics, and traces from the Loggerhead backend over HTTP. Nothing leaves your Mac.

Before you start

Install the Loggerhead app and open it. The MCP server exits when no backend answers.
Open Settings → AI tools (MCP) in the app. The page shows the snippets below with the real binary path, each with a Copy button.

Claude Code

Run this inside your project:

claude mcp add loggerhead -- "/Applications/Loggerhead.app/Contents/Resources/loggerhead-mcp"

Or add a .mcp.json file at the project root, so the whole team gets the server:

{
  "mcpServers": {
    "loggerhead": {
      "command": "/Applications/Loggerhead.app/Contents/Resources/loggerhead-mcp"
    }
  }
}

Claude Code asks you to approve the server once, on the next start.

Claude Desktop

Add the same mcpServers block to ~/Library/Application Support/Claude/claude_desktop_config.json.

Cursor, Codex, Windsurf, and other MCP clients

Every stdio MCP client takes the same two values:

Field	Value
Server name	`loggerhead`
Command	`/Applications/Loggerhead.app/Contents/Resources/loggerhead-mcp`

Put them in the client’s MCP config file. For Cursor that file is .cursor/mcp.json, with the same JSON as above.

How the server finds the backend

The backend picks a free port for its API on each launch. It writes that port to a file next to its database, and the MCP server reads the file. You do not set a port. To point the server at a specific backend, set the LOGGERHEAD_BACKEND_URL environment variable, or pass --backend-url.

What the AI tool can do

Tool	Purpose
`query_logs`	Search logs by text, severity, and time range.
`query_metrics`	Read time-series metrics over a time range.
`query_traces`	Find traces by service, operation, duration, and time range.
`get_trace`	Read every span in one trace.
`get_receiver_info`	Report the effective OTLP ports and addresses of the root receiver.

The loggerhead://stats resource reports the total counts of logs, metrics, and spans.

Connect the project’s telemetry

The AI tool can also connect the project’s own telemetry to Loggerhead and check the result with these tools. The AI tool calls get_receiver_info to find the OTLP addresses, so you do not copy a port. Paste the prompt from Connect your project with one prompt.