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 a complete MCP server that lets Claude, coding agents, and IDE plugins access observability data, search traces, and manage fixes directly from your agent workflows.

What You Can Do

With Neatlogs MCP, your agents can:

• Search production traces — Free-text query with filters for framework, model, detection, duration, token count, and cost
• Get full trace context — Fetch complete span trees with inputs, outputs, code locations
• List detections — See which detections (Hallucination, Jailbreak, Task Failure, …) are active
• Track detection trends — Analyze hourly/daily/weekly occurrence rates
• Read fixes — List all fix suggestions with root cause and recommended actions
• Manage fixes — Accept, dismiss, update status, and edit fix fields
• Review fix history — List, fetch, and restore saved content versions of a fix
• Log agent work — Push traces back to Neatlogs from your agent's execution
• Investigate fixes — Reload the investigation trail that produced a fix

Getting Started

Step 1: Get Your API Key

Each Neatlogs project has its own API key. Go to Settings → API Keys in the dashboard, pick your project, 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 mcp --api-key YOUR_PROJECT_KEY

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 on hosted Neatlogs, or your own host's /mcp if you self-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.

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 that created them — reusing a session id with a different project's 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 are also cleaned up when the underlying connection closes. If a session id stops resolving, just initialize a new one.

Rate Limiting

• Limit: 60 requests per 60 seconds
• Applies to: POST and DELETE only
• Excludes: GET (SSE streaming) to avoid breaking long-lived connections
• Response: 429 Too Many Requests if exceeded

Retry with exponential backoff. Most tools complete in under 1 second so 60 req/min is generous for typical workflows.

Tool Overview

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("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(error_message)
3. Fetches matching production traces
4. Shows top detections via list_detections()
5. Links to Neatlogs fixes panel

Workflow 3: Agent Managing Fixes

1. Agent sees triage_list() shows 5 draft fixes
2. Calls triage_get(fix_id) to review root cause
3. Dispatches fix to Claude Code
4. Calls triage_update_status(fix_id, "in_progress")
5. After deployment, calls triage_update_status(fix_id, "resolved")

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

Error Handling

Authentication Errors

Validation Errors

Server Errors

All error responses include an error field with details. 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 → API Keys.

"Too many requests"

Hit rate limit (60/min). Implement exponential backoff or reduce call frequency.

"Session not found" / "Unknown sessionId"

Session was torn down or the connection closed. Initialize a new session (omit the mcp-session-id header on the next initialize).

"Session belongs to a different project"

Using an API key from one project to access another project's session. Create a new session with the correct key.

A tool is missing from tools/list

On self-hosted deployments, tools are enabled per-deployment in the backend tools.yaml. On hosted Neatlogs, all current tools are enabled — update your client if it's pinned to an old tool list.

Next Steps

• Read the MCP Tools Reference for detailed tool schemas
• Check Span Kinds for MCP_TOOL documentation
• See Long-Running Sessions for session monitoring from agents