Set up the MCP server

Loggerhead ships an MCP server inside the Mac app. The app hosts the endpoint on a local port, and the small loggerhead-mcp bridge that an AI coding tool starts forwards the session to it. The tools read logs, metrics, and traces from the app’s own store. Nothing leaves your Mac.

Before you start

1. Install the Loggerhead app and open it. The bridge exits when the app is not running.
2. Open Settings → AI analysis in the app. The AI coding tools rows have an Add button per tool that writes the server into that tool’s config, and a Copy config button for any other MCP client.

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 bridge finds the app

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

An MCP client that speaks Streamable HTTP can skip the bridge and connect to http://127.0.0.1:<port>/mcp, with the port from that file.

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.