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 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

The Add button writes the server into the user scope of ~/.claude.json, so Claude Code has it in every project. To do the same from a terminal, run:

claude mcp add --scope user 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 in that project:

{
  "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

Claude Desktop installs an extension file. Every Loggerhead release publishes one.

1. Open the latest loggerhead-mcp release and download loggerhead-mcp.mcpb.
2. Open the Claude Desktop settings, go to Extensions, and install the file.

The extension carries its own copy of the bridge. A Loggerhead update does not change that copy, so install the extension again after an update.

To keep one copy only, add the same mcpServers block to ~/Library/Application Support/Claude/claude_desktop_config.json instead. That path runs the bridge inside the app you have, so the two always agree.

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 binds its MCP endpoint on a fixed ladder of local ports: 9696, then 19696, then 29696, the first one that is free. The bridge tries the same three ports in the same order and stops at the first one that answers. You do not set a port, and the bridge needs no permission to read the app’s files. 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:9696/mcp. When that port does not answer, try 19696, then 29696.

Check the connection

Open Settings › AI in the app. The MCP server row is at the top of the AI coding tools card.

The row shows	What it means
Running, with 127.0.0.1 and a port	The endpoint is on the port ladder, and the bridge can find it.
Last request from Claude Code 12s ago. Last tool: query_logs.	An AI tool reached the app. The row names the tool and the last tool call.
No AI tool has connected since Loggerhead started.	No AI tool sent a request. Restart the AI tool, then ask it to use a Loggerhead tool.
Running with an amber dot	Other programs use all three ports, so the app took another port. The bridge cannot find that port. Stop the program on port 9696, then open Loggerhead again.
Not running	The endpoint did not start. The row gives the reason.

The row starts empty each time the app opens. A switch to another environment also starts it again.

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.
query_improvements	List the telemetry-quality findings, with filters for impact, source, and kind.
list_environments	List every workspace and environment on this Mac, with the receiver ports.
list_lint_rules	List the lint rules of a workspace with their state, thresholds, exceptions, ignored findings, and recent changes.
query_ai_findings	List the findings of the last AI analysis run, with filters for impact and source. It does not start a run.
set_lint_rule_enabled, set_lint_threshold, reset_lint_threshold	Switch a lint rule on or off, or change a threshold, for a workspace. A reason is required.
add_lint_exception, remove_lint_exception	Add or remove an exception that hides the findings of one rule for a service, a metric, an attribute key, an operation, or a log message.
ignore_finding, unignore_finding	Ignore one finding by its id, or stop the ignore.
mark_finding_fixed	Mark one finding fixed after a code change. Loggerhead then judges it by the telemetry after the fix.

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

The bundle and the Official MCP Registry

Loggerhead is in the Official MCP Registry as com.getloggerhead/loggerhead. The entry points at loggerhead-mcp.mcpb, the bundle on each loggerhead-mcp release.

The bundle holds the same bridge that the app carries. Which one you use depends on the client, not on the version:

Client	What it takes	Use
Claude Code, Cursor, Codex, Windsurf	A command path	The bridge inside the app. claude mcp add reads no registry and installs no bundle.
Claude Desktop	An extension file	The .mcpb bundle, or the mcpServers block above.
A client that reads the registry	The registry entry	The registry entry, which downloads the same bundle.

The path in the sections above is therefore correct for a command-line tool, and it stays correct. Prefer it where the client accepts a path, because the bridge then always matches the app.

Loggerhead in MCP directories

The directories that list MCP servers point here. The listing reads: Read the logs, metrics, and traces of the app you are editing, from the Loggerhead Mac app, over MCP. The tools read the telemetry. Seven tools change the lint rules of a workspace, each with a reason that the user sees and can undo in the app. One tool marks a finding fixed after a code change. The server listens on loopback only, and nothing leaves the Mac. The tools are in the table above, and every parameter is in the Tools reference.

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.