---
title: "Set up the MCP server"
description: "Give Claude Code, Cursor, Codex, or any MCP client a window into your running app."
source: "https://getloggerhead.com/docs/mcp-server/setup/"
---

# Set up the MCP server

> Give Claude Code, Cursor, Codex, or any MCP client a window into your running app.

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:

```bash
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:

```json
{
  "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](https://github.com/rubics-code/loggerhead-mcp/releases/latest) 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](https://registry.modelcontextprotocol.io) as `com.getloggerhead/loggerhead`. The entry points at `loggerhead-mcp.mcpb`, the bundle on each [`loggerhead-mcp` release](https://github.com/rubics-code/loggerhead-mcp/releases/latest).

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](/docs/mcp-server/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](/docs/connect-your-ai-tool/connect-your-project-with-one-prompt/).