MCP

Connect Claude Code, Codex, Gemini CLI, or any MCP client to your logs with one command. Your agent reads production while it debugs.

LogNorth speaks the Model Context Protocol at POST /mcp. Your coding agent reads production logs while it fixes the bug, in the same pane as the code.

Requires LogNorth v0.16.0 or later. On an older version, run the install line again to update, or lognorth update on a server of the older installer.

The tools run inside the LogNorth process, so a current server has current tools. On your machine, agents start north mcp, a small open-source relay that holds the URL and the key in one file.

Setup

1. Create an agent key

Open Settings > Developer and create an agent key. It is read-only and starts with lgn-agent-. It is separate from the app keys your SDKs use to send events.

2. Run one command

The same page shows this command with your URL and key filled in. Run it in your terminal:

curl -fsSL https://lognorth.com/cli | sh -s -- https://logs.yoursite.com lgn-agent-...

✓ Connected to logs.yoursite.com: shop-prod, shop-staging
  Saved to ~/.config/lognorth/remote.json, readable by you only

Add LogNorth to Claude Code, Codex, Gemini CLI and Cursor? [Y/n]
  ✓ Claude Code  plugin lognorth
  ✓ Codex        plugin lognorth
  ✓ Gemini CLI   extension lognorth
  ✓ Cursor       ~/.cursor/mcp.json

Restart your agent, then ask it: what is broken in production?

It installs north without sudo, checks the key against your server before it saves anything, and adds LogNorth to each agent it finds: the plugin in Claude Code, Codex, and Gemini CLI, and north mcp in Cursor’s ~/.cursor/mcp.json. The plugin brings the tools, the investigation skill, and /lognorth:investigate.

That’s it. Restart your agent. In Claude Code, /mcp lists the server.

How it connects

Each agent starts north mcp. It reads ~/.config/lognorth/remote.json and relays the agent’s calls to your server over HTTPS. The key is only in that file. It is never in an agent config or in a dotfiles repo.

New key? Run north connect with it. Running agents use it on their next call, with no restart.
New agent? Run north agents to add LogNorth to it.
Something wrong? Run north. It says which server it reads, or that it is not connected yet.

Keep the key out of the chat

Connect in your terminal, not inside the agent. A key pasted into a chat goes to your AI provider and stays in the transcript. north connect hides the key as you paste it. /lognorth:connect in Claude Code checks the connection and tells you what to run, but never asks for the key.

Other clients

After north connect, any MCP client takes the same local command:

{
  "mcpServers": {
    "lognorth": { "command": "north", "args": ["mcp"] }
  }
}

That is the shape north agents writes for Cursor, and the one for Windsurf (~/.codeium/windsurf/mcp_config.json). GitHub Copilot CLI and VS Code install the same plugin from karloscodes/lognorth-releases. An app started from the Dock may not see your shell’s PATH; if it cannot find north, use the full path from command -v north.

A client can also skip north and talk to https://logs.yoursite.com/mcp directly, with the agent key as a Bearer token:

claude mcp add --transport http lognorth https://logs.yoursite.com/mcp \
  --header "Authorization: Bearer lgn-agent-..."

That puts the key in the client’s config file. Keep that file out of git.

Ask

Every LogNorth alert email ends with one line. Paste it into Claude Code:

/lognorth:investigate /api/checkout

Claude: [list_alerts, endpoint_timeline, search_logs, get_event]

/api/checkout fails 8% of the time since 14:05, normally 1%.
All 212 failures are "Stripe timeout after 2s" at
app/payments/charge.rb:41.

[git log around 14:05]

a3f9c1e, deployed 14:02, cut the Stripe timeout from 30s to 2s.
Restore the 30s timeout; the diff is below.

The log says what broke and when. Your repo says why. The agent has both, so it can go from the alert to the commit.

Or just ask: “is anything broken in production?”

Tools

Tool	What it does
`list_apps`	Lists your apps with their ids. Call it first when a tool needs an `app_id`.
`list_alerts`	What is alerting now: error rate spikes and drift, traffic drops, and apps down on their uptime ping. Each alert says when it started and what normal is.
`list_endpoints`	Every endpoint of one app with its requests, errors, error rate, and average duration, most broken first.
`endpoint_timeline`	Requests, errors, and error rate for one endpoint over time, next to its normal level.
`uptime_timeline`	The app’s uptime ping: the latest result, 24h uptime, and the last 24 hours in 15-minute bars that say why pings failed.
`list_issues`	Grouped errors with occurrence counts, trend, and when each was first and last seen.
`search_logs`	Searches requests by text, issue, errors only, and time window.
`get_event`	One event with its full context and every event sharing its trace.

list_alerts, endpoint_timeline, and the issue and until arguments need the release after v0.16.2. list_endpoints, uptime_timeline, and after_id need v0.20.0.

list_alerts

Takes an optional app_id. Returns alerts, one per endpoint, with kind (error_rate or silence), severity, since, current, normal, and a one-line summary. Apps that stopped answering their uptime ping are in down.

list_endpoints

Argument	Example	Description
`app_id`	`2`	The app. Optional when there is only one
`since`	`1h`, `24h`, `7d`	How far back. Default `1h`, at most 29 days
`limit`	`50`	Max endpoints, 1 to 200. Default `50`

Returns endpoints, most broken first: path, total, errors, error_rate, and avg_duration in milliseconds.

endpoint_timeline

Argument	Example	Description
`path`	`/api/checkout`	The endpoint. Required
`app_id`	`2`	The app. Optional when only one app has this path
`since`	`30m`, `6h`, `7d`	How far back. Default `6h`, at most 29 days

Steps are 5 minutes up to 24 hours back and 1 hour beyond. A step with no traffic is included as zero, so a silence shows as a gap.

uptime_timeline

Takes an optional app_id, needed only when there are several apps. Returns status (up, failing, down, pending, off, or none), latency_ms, uptime_24h, down_since, last_failure, and 96 bars of 15 minutes. Each bar has checks, fails, and failures: why pings failed, like 503 or no answer within 5s. See Uptime.

search_logs

Argument	Example	Description
`search`	`timeout`	Text to match in the message and context
`errors_only`	`true`	Only requests that failed. Default `false`
`issue`	`9f2c…`	The `hash` of an issue from `list_issues`: only its events
`since`	`15m`, `2h`, `7d`, or an RFC 3339 time	Start of the window. Default `1h`
`until`	same forms as `since`	End of the window. Default now
`app_id`	`2`	Restrict to one app, from `list_apps`
`limit`	`50`	Max events, 1 to 200. Default `20`
`after_id`	`48213`	Only events stored after this id, oldest first. To follow the log, pass the highest id you have seen. `since` then has no default

The defaults are deliberately small. An agent that needs more asks for more, and that keeps the first answer cheap.

get_event

Takes one id from search_logs. Returns the event, its parsed context, and relatedEvents: every other event with the same trace_id. That is how the agent reconstructs the whole request instead of guessing from one line. error_file and error_line point at the code.

What the agent cannot do

Every tool is read-only. There is no tool to write an event, mute an issue, change a setting, or delete anything. The agent can look, never touch.

The agent key only reaches these read tools. It cannot ingest events and it cannot sign in to the web UI.

Privacy

Your logs stay on your server. The agent asks your instance, your instance answers, and only that answer travels to your AI provider along with the rest of your conversation. LogNorth never sees any of it.

For a closed loop, point a local model at the same endpoint. Your key, your provider choice, your tradeoffs.

Protocol notes

Transport is Streamable HTTP. One JSON-RPC 2.0 request per POST, one JSON response back.
Protocol revisions: 2025-06-18, 2025-03-26, 2024-11-05. The server answers with your client’s revision when it knows it, otherwise with the newest.
Notifications get 202 with no body.
Auth is the agent key as Authorization: Bearer lgn-agent-.... Without it the endpoint returns 401 and no data.

Call it by hand to check a setup:

curl -X POST https://logs.yoursite.com/mcp \
  -H "Authorization: Bearer lgn-agent-..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

What to ask

Once it is connected, ask in plain English:

“What’s breaking in production?”
“Show me the last 10 errors on /checkout”
“What happened during request abc-123?”
“Did the deploy fix the Stripe timeouts?”
“What broke in the last hour?”

The agent picks the tools. You read the answer.