MCP Integration

The Model Context Protocol (MCP) is a standard that allows AI agents and IDEs to interact with external systems through a unified tool interface. Neatlogs exposes an MCP server that lets coding agents and IDE plugins access observability data, search traces, author detections, and work on the fixes behind incidents directly from an agent workflow.

What You Can Do

With Neatlogs MCP, your agents can:

• Search production traces - Free-text query with filters for workflow, framework, model, detection, duration, token count, errored spans, and cost
• Get full trace context - Fetch a trace's spans with inputs, outputs, code locations, detections, and evaluations
• Read analytics - Pull dashboard KPIs, cost, errors, latency, and tool breakdowns for a time window
• List detections - See which detections (Hallucination, Jailbreak, Task Failure, …) the project runs
• Track detection trends - Analyze hourly/daily/weekly occurrence rates
• Author detections - Dry-run a regex or conditional rule, then create the detection with a 14-day backfill
• Read fixes - List the fixes behind incidents, with root cause, evidence, and recommended actions
• Manage fixes - Accept, dismiss, update status, and edit fix fields
• Review fix history - List, fetch, and restore saved content versions
• Log agent work - Push traces back to Neatlogs from your agent's execution
• Investigate - Reload the investigation trail that produced a fix

Getting Started

Step 1: Get Your API Key

Each Neatlogs project has its own API key. Open Settings → Project → API keys in the dashboard with the project selected, and copy its key.

Step 2: Connect Your Agent or IDE

The fastest path is the wizard, which wires the MCP server into Claude Code or Cursor for you:

npx @neatlogs/wizard@latest mcp

It prompts for the project API key. For an EU project, add --region eu.

To connect manually, add a neatlogs entry to your client's MCP config (.mcp.json for Claude Code, .cursor/mcp.json for Cursor):

{
  "mcpServers": {
    "neatlogs": {
      "type": "http",
      "url": "https://ingest.neatlogs.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_PROJECT_KEY"
      }
    }
  }
}

The MCP server lives at /mcp on the same host as your SDK endpoint: https://ingest.neatlogs.com/mcp in the US region, https://eu.ingest.neatlogs.com/mcp in the EU region, or your dedicated deployment's ingest host.

Authentication: Include the key in either header:

• Authorization: Bearer <your-api-key> (preferred — what most MCP clients send)
• x-api-key: <your-api-key> (legacy, still accepted)

Step 3: Verify and Start Using Tools

Restart your editor and the Neatlogs tools appear in your agent's tool list. Ask the agent to call ping to verify the connection, and whoami to confirm which project the session is bound to. From there it can call any tool — for example, search traces for a specific error.

Connection Methods

POST https://ingest.neatlogs.com/mcp
Authorization: Bearer <your-api-key>
Content-Type: application/json
Accept: application/json, text/event-stream

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": { "name": "my-agent", "version": "1.0" }
  }
}

POST https://ingest.neatlogs.com/mcp
Authorization: Bearer <your-api-key>
Content-Type: application/json
Accept: application/json, text/event-stream
mcp-session-id: <session-id-from-initialize>

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "search_traces",
    "arguments": {
      "query": "timeout"
    }
  }
}

GET https://ingest.neatlogs.com/mcp/sse
Authorization: Bearer <your-api-key>

# Connection opens, receives events
# Then POST messages to:
POST https://ingest.neatlogs.com/mcp/messages?sessionId=<session-id>

Authentication Patterns

Bearer Token (Standard)

Authorization: Bearer <your-project-api-key>

Preferred by MCP clients. Works with any integration.

Legacy Header (x-api-key)

x-api-key: <your-project-api-key>

Older integrations. Still supported for backward compatibility.

Scope

API keys are unique per project. Each key grants access to one project only - the session sees only that project's traces, detections, and fixes.

Service accounts

An organization service-account token (nlsa_ prefix) can also open a session. Send the target project in an x-project-id header. These sessions expose only read tools, each checked against the account's permissions and scopes. See the MCP Tools Reference.

Session Management

Creating a Session

The initialize request creates a new session:

POST https://ingest.neatlogs.com/mcp
Authorization: Bearer <your-api-key>

The server returns the session id in the mcp-session-id response header. Store this for subsequent calls.

Resuming a Session

Reuse an existing session by including the header:

POST https://ingest.neatlogs.com/mcp
Authorization: Bearer <your-api-key>
mcp-session-id: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Same session, same tools advertised, same context. Sessions are bound to the project and key that created them - reusing a session id with a different key returns 403.

Cleaning Up

Send DELETE to tear down a session:

DELETE https://ingest.neatlogs.com/mcp
Authorization: Bearer <your-api-key>
mcp-session-id: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Sessions also close when the underlying connection closes or after 10 minutes without requests. If a session id stops resolving (404 Session not found), initialize a new one.

Capacity

Neatlogs caps concurrent sessions at 128 per project and 256 per organization. Beyond that, new sessions get 429 with a Retry-After header. Reuse sessions instead of opening one per request.

Rate Limiting

• Limit: 60 tool calls per 60 seconds per project by default
• Shared by: every session and key for the project
• Counts: tools/call requests, except ping
• Doesn't count: initialize, tools/list, session teardown, and GET/SSE streams
• Response: 429 with code MCP_TOOL_CALL_RATE_LIMITED, retryAfterSeconds, and a Retry-After header. Responses also carry RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers.

Retry after the indicated delay, with backoff. Each tool call has a 15-second time limit.

Tool Overview

The default project-key catalog includes the 26 tools below. Deployments and authentication scope can change which tools are available; use the authenticated session's tools/list as the source of truth.

See the MCP Tools Reference for detailed schemas and examples.

Common Workflows

Workflow 1: Agent Debugging Its Own Output

1. Agent completes a task
2. Calls log_trace() to push execution trace
3. Calls search_traces(query: "timeout", min_duration: 5000) to find similar slow traces
4. Calls get_trace_context(trace_id) to compare
5. Uses context to improve next attempt

Workflow 2: IDE Plugin Finding Root Causes

1. Developer sees error in IDE
2. Plugin calls search_traces(query: error_message)
3. Fetches matching production traces
4. Shows top detections via list_detections()
5. Links to the matching incident in Neatlogs

Workflow 3: Agent Working on a Fix

1. Agent calls triage_list(status: "draft") and finds five drafts
2. Calls triage_get(triage_id) to review root cause
3. Asks the user for their team email, then calls triage_accept(triage_id, user_email)
4. Calls triage_update_status(triage_id, user_email, "in_progress") and implements the change
5. After deployment, calls triage_update_status(triage_id, user_email, "resolved", resolution_note)

Workflow 4: Monitoring Regressions

1. Agent calls list_detections()
2. Picks a detection to watch, e.g. "Hallucination"
3. Calls get_detection_trend(detection_name: "hallucination", period: "7d", granularity: "day")
4. If trending up, digs into matching traces via search_traces(detection_name: "hallucination")

Workflow 5: Creating a Detection

1. Agent calls list_detection_groups() and picks a group_id (or create_detection_group)
2. Calls preview_detection(type: "regex", config: { output_pattern: "payment failed" })
3. If total_count > 0, calls create_detection(display_name, group_id, type, config)
4. Calls get_detection_status(detection_id) to follow the 14-day backfill

Error Handling

Authentication Errors

Validation Errors

Server Errors

Transport errors return JSON with an error field. A tool that fails returns a normal result with isError: true and an errorCode such as invalid_argument, not_found, or not_enabled; see Errors. Calling a tool that isn't enabled returns a JSON-RPC error - disabled tools are never advertised in tools/list, so a well-behaved client won't hit this.

Best Practices

Troubleshooting

"API key required"

Missing or malformed Authorization header. Ensure the header is present and the format is correct.

"Invalid API key"

Key doesn't match any project. Copy it again from Settings → Project → API keys, and check that the MCP URL matches the project's region.

"Too many requests"

The project's tool-call budget (60 per minute by default) is used up, across all of its sessions. Wait for Retry-After and reduce call frequency.

"Session not found" / "Unknown sessionId"

Session was torn down, expired after 10 idle minutes, or the connection closed. Initialize a new session (omit the mcp-session-id header on the next initialize).

"Session belongs to a different project"

The session was created with a different key. Create a new session with the key you're using now.

A tool or parameter returns not_enabled

Some advertised parameters, such as fields on search_traces and selective-context options on get_trace_context, are not enabled yet. Omit them.

A tool is missing from tools/list

Tools are enabled per deployment and authentication scope. Initialize an authenticated session and call tools/list to see the tools that session can use. Call ping to check connectivity. Refresh your client if it is pinned to an older tool list; the hosted /mcp/health endpoint is not a public, unauthenticated check.

Next Steps

• Read the MCP Tools Reference for detailed tool schemas
• Check Span Kinds for MCP_TOOL documentation
• See Long-Running Sessions to follow a cloud coding-agent run from an incident until it opens a pull request