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 — Query by text, framework, error type, latency, cost
• Get full trace context — Fetch complete span trees with inputs, outputs, code locations
• List detections — See what anomalies, regressions, and errors are active
• Track detection trends — Analyze hourly/daily occurrence rates
• Read fixes — List all suggestions/fixes with root cause and recommended actions
• Manage fixes — Accept, dismiss, update status, and mark as deployed
• Log agent work — Push traces back to Neatlogs from your agent's execution
• Investigate fixes — Review investigation steps and collaborate on solutions

Getting Started

Step 1: Get Your API Key

1. Go to Settings → API Keys in Neatlogs
2. Click Create API Key
3. Copy the key and store securely

Step 2: Connect Your Agent or IDE

Use the API key to authenticate with the MCP server at:

https://neatlogs.com/mcp

Authentication: Include the key in either header:

• Authorization: Bearer <your-api-key>
• x-api-key: <your-api-key>

Step 3: Start Using Tools

Once connected, your agent can call any enabled tool. Example: search traces for a specific error.

Connection Methods

POST https://neatlogs.com/mcp
Authorization: Bearer <your-api-key>
Content-Type: application/json
mcp-session-id: <optional-session-id>

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "call_tool",
  "params": {
    "name": "search_traces",
    "arguments": {
      "query": "timeout"
    }
  }
}

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

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

GET https://neatlogs.com/mcp/health

Response:
{
  "status": "ok",
  "tools_enabled": [
    "ping",
    "whoami",
    "log_trace",
    "search_traces",
    "triage_list",
    ...
  ]
}

Authentication Patterns

Bearer Token (Standard)

Authorization: Bearer sk_proj_abc123def456...

Preferred by MCP clients. Works with any integration.

Legacy Header (x-api-key)

x-api-key: sk_proj_abc123def456...

Older integrations. Still supported for backward compatibility.

API Key Format

Keys start with sk_proj_ and are unique per project. Each key grants access to one project only.

Session Management

Creating a Session

First request creates a new session automatically:

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

Server returns mcp-session-id header. Store this for resuming.

Resuming a Session

Reuse an existing session by including the header:

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

Same session, same tools advertised, same context.

Cleaning Up

Send DELETE to tear down a session:

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

Sessions also auto-cleanup after inactivity.

Rate Limiting

• Limit: 60 requests per 60 seconds per API key
• 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 /reference/mcp-tools.mdx 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("latency > 5s") 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. Filters for "prompt_regression"
3. Calls get_detection_trend("prompt_regression", "day")
4. If trending up, creates alert or investigation

Error Handling

Authentication Errors

Validation Errors

Server Errors

All error responses include an error field with details.

Best Practices

Troubleshooting

"API key required"

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

"Invalid API key"

Key doesn't exist or is revoked. Regenerate in Settings → API Keys.

"Too many requests"

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

"Unknown sessionId"

Session expired or doesn't exist. Create a new session by omitting the header.

"Session belongs to different project"

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

Tools not appearing in /health

Tool is disabled in backend tools.yaml. Contact your ops team to enable it.

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