# Loggerhead for coding agents

> Loggerhead is a native macOS app that receives OpenTelemetry logs, metrics, and traces on the developer's own Mac. It serves that data back to you over the Model Context Protocol, so you can read how the application behaved after you changed it. Nothing leaves the machine.

## What this is

Loggerhead makes one promise to the developer: "Your coding agent reads your app's logs, metrics, and traces." You are that agent, and this file is how you read the data.

Loggerhead replaces a Docker stack of collector, database, and dashboard with one app. It holds every record in a DuckDB file on the developer's disk. There is no account, no hosted service, and no public API.

Platform: macOS 15+ · Apple silicon & Intel.

## When to use it

Use the Loggerhead MCP tools when you need evidence about a running application rather than a guess:

- A test fails and you need the log lines and the trace of the failed request.
- You changed a handler and you want to compare latency before and after.
- A user reports an error and you need the trace that carries it.
- You want to know whether the telemetry the application emits is any good.

## Connect a project

The application under development sends OpenTelemetry data to the Loggerhead receiver on loopback. Set these variables in the way the project already sets environment variables:

```bash
OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_SERVICE_NAME=<the service name>
```

The receiver prefers port 4317 for gRPC and 4318 for HTTP. When another program holds a port, the app moves along a fixed ladder and shows the port it ended on. Always read the port from the app's Collectors page, or call the `get_receiver_info` tool, instead of assuming 4318.

Full steps: https://getloggerhead.com/docs/getting-started/connect-your-first-app/

## Read the data

Add the MCP server to the coding tool. The bridge ships inside the app:

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

Any stdio MCP client takes the same command. For a project-wide server, write `.mcp.json` at the project root:

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

The app must be open. The bridge exits when it is not.

Full steps: https://getloggerhead.com/docs/mcp-server/setup/

## Tools

| Tool | What it answers |
| --- | --- |
| `query_logs` | Search and filter log records by text, severity, and time. |
| `query_metrics` | Read time-series metrics by name pattern and time. |
| `query_traces` | Search traces by service, operation, duration, and time. |
| `get_trace` | Read every span of one trace by trace ID. |
| `get_receiver_info` | Report the effective OTLP ports and the addresses to send to. |
| `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. 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 every environment of a workspace. A reason is required. |
| `add_lint_exception`, `remove_lint_exception` | Hide the findings of one rule for a service, a metric, an attribute key, an operation, or a log message. A reason is required. |
| `ignore_finding`, `unignore_finding` | Ignore one finding by its id, or stop the ignore. A reason is required. |
| `mark_finding_fixed` | Mark one finding fixed after a code change. Loggerhead then judges the finding by the telemetry after the fix. |

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

The first nine tools only read. The next seven tools change the lint rules of a workspace or ignore a finding. Each of them needs a reason, and the user can undo the change on the Rules tab of the Linting page. Call `mark_finding_fixed` after the fixed code runs; new telemetry that trips the rule opens the finding again. No tool deletes telemetry, starts an AI analysis, or reaches another machine.

Reference: https://getloggerhead.com/docs/mcp-server/tools-reference/

## Telemetry linting

Loggerhead reads what the application emits and reports the noise, the leaks, and the gaps. Call `query_improvements` and act on what it returns. Each finding carries a written fix you can apply to the project's code: a log line that repeats a million times an hour, an email address in a log field, a label with unbounded cardinality, a log with no trace context, a metric that stopped.

Every finding names the rule that made it. Call `list_lint_rules` to read the rule's thresholds and explain why the finding fired. Fix the telemetry at the source first. When a finding is a false positive for the project, add an exception or ignore the finding with a reason; the user sees each change on the Rules tab of the Linting page and can undo it.

The AI analysis finds problems that one rule cannot find. Call `query_ai_findings` to read the findings of the last run. A model made them, so check each one against the telemetry. The user starts a run in the app; with the status `not_run`, ask the user to run it.

Reference: https://getloggerhead.com/docs/telemetry-linting/what-it-checks/ and https://getloggerhead.com/docs/telemetry-linting/tune-the-rules/

## Limits

- macOS only. There is no Linux or Windows build, and no hosted version.
- The receiver binds `127.0.0.1`. A container reaches it at `host.docker.internal`, not at `localhost`.
- Loggerhead only knows what was sent to it. A service that does not export to the receiver is invisible to every tool.
- The MCP server has no network surface. It is not reachable from another machine, and there is no OpenAPI document to fetch.

## More

- Documentation index for agents: https://getloggerhead.com/llms.txt
- Every documentation page in one file: https://getloggerhead.com/llms-full.txt
- Glossary of the terms used here: https://getloggerhead.com/docs/reference/glossary/
- Documentation home: https://getloggerhead.com/docs/