Overview

When a support ticket comes in ("checkout failed for user 4417 around 14:30"), answering it usually means opening a DB client, the AWS Console, and a logging platform, hand-writing a query in each, then manually cross-referencing timestamps and ids across all three. This server turns that into a conversation with an MCP client.

Features include:

• 🐘 PostgreSQL — schema discovery, validated read-only SELECT execution, PII-masked sample rows, and catalog-driven identifier/store lookup (no hardcoded table list).
• ☁️ AWS CloudWatch — log group discovery, Logs Insights queries (cost-capped by bytes scanned), pattern-based log filtering, and metric statistics.
• 🟢 New Relic — event type and log field discovery (keyset()), correlation-id detection, and validated NRQL execution.
• 🛡️ Guardrails, not trust — every query is AST-parsed (SQL) or pattern-validated (NRQL/CloudWatch) before it touches the network; results are PII-redacted before they're returned.

The server does not generate queries itself. The client model (Claude Desktop, Cursor) writes the query, using schema/field-discovery tools and a curated query cookbook this server exposes as grounding context — the server's job is to make sure the model has enough context to write a correct query, and to validate + execute whatever it writes safely. See docs/design.md (§3.1) for the full rationale.

Cross-source correlation — matching a request_id/order_id across the DB and both log sources — is currently done by the client model itself; there's no composite "investigate this ticket end-to-end" tool yet (see docs/design.md §4.5 for what's not implemented).

Architecture

Quick Start

Fastest: run the published package with uvx

No clone, no Docker, no port. Install uv, then add this to your MCP client config (Claude Desktop claude_desktop_config.json, Cursor .cursor/mcp.json). The client launches the server itself over stdio, and uvx downloads and caches the package on first run:

{
  "mcpServers": {
    "investigation": {
      "command": "uvx",
      "args": ["opsinsight-mcp"],
      "env": {
        "DB_URL": "postgresql+asyncpg://readonly_user:pass@host:5432/dbname",
        "CLOUDWATCH_REGION": "ap-south-1",
        "CLOUDWATCH_ACCESS_KEY_ID": "...",
        "CLOUDWATCH_SECRET_ACCESS_KEY": "...",
        "CLOUDWATCH_ALLOWED_LOG_GROUP": "/app/prod",
        "NEW_RELIC_API_KEY": "NRAK-...",
        "NEW_RELIC_ACCOUNT_ID": "..."
      }
    }
  }
}

Claude Code: claude mcp add -e DB_URL=... investigation -- uvx opsinsight-mcp.

Only set the variables for the sources you use (see What each source needs). In this mode there is no .env file — the env block is the configuration. To run an unreleased version straight from GitHub, use "args": ["--from", "git+https://github.com/Vignesh-2552/mcp-log-db-investigator", "opsinsight-mcp"].

Prerequisites (running from source)

• Python 3.11+
• uv
• Access credentials for whichever source(s) you want to use — see What each source needs below. You don't need all three; a source you skip just errors at call time instead of blocking startup.

Installation

uv sync
copy .env.example .env
# edit .env — fill in DB_URL and/or the CloudWatch/New Relic blocks you need
uv run investigation-server

The server starts on http://127.0.0.1:8001/mcp by default (streamable HTTP transport; change it with SERVER_PORT). It has no built-in HTTP authentication, so only set SERVER_HOST to a non-loopback address when access is protected by an authenticated proxy or equivalent network control.

Docker

For a long-running HTTP server (shared by a team, or on a server host), run the image published to GHCR on every merge to main:

docker run --rm -p 127.0.0.1:8000:8000 --env-file .env -e SERVER_HOST=0.0.0.0 -e SERVER_PORT=8000 ghcr.io/vignesh-2552/mcp-log-db-investigator:latest

Then point the client at http://localhost:8000/mcp. To build the image yourself instead: docker build -t investigation-mcp . and use investigation-mcp as the image name.

Three things differ from the local (uv run) path:

• SERVER_HOST must be overridden to 0.0.0.0 — the default 127.0.0.1 would only be reachable from inside the container.
• SERVER_PORT must match the container side of -p (8000 above). The app default and .env.example both use 8001; -e overrides the .env value.
• Use host.docker.internal instead of localhost in DB_URL for a database running on your own machine.
• AWS_PROFILE won't work (there's no local AWS config file inside the image) — use CLOUDWATCH_ACCESS_KEY_ID/CLOUDWATCH_SECRET_ACCESS_KEY in .env instead if you need CloudWatch tools.

What each source needs

See .env.example for every available variable, including tuning knobs (row limits, time-window caps, timeouts) that all ship with working defaults.

Configure Your AI Assistant

Cursor — .cursor/mcp.json:

{
  "mcpServers": {
    "investigation": {
      "type": "http",
      "url": "http://localhost:8001/mcp"
    }
  }
}

Claude Desktop — same shape in claude_desktop_config.json.

Usage Examples

Investigate a failed order

Ask:

Why did checkout fail for order 88213 around 14:30 IST yesterday?

Find a user's records across the database

Ask:

Find every row across the schema that references user_id 4417.

Trace a request through the logs

Ask:

Pull the log lines for order_id 88213 from /aws/ecs/checkout-svc for the last hour.

Cross-check against New Relic

Ask:

What event types have data in New Relic in the last hour, and what fields does the Log event type have?

MCP Server API

For a junior-friendly reference with inputs, output structures, examples, and tool update guidance, see docs/tool-reference.md.

Resources: schema://db/tables, schema://db/table/{name}, logs://groups, docs://query-cookbook.

Security Model

Every db_*/cw_*/nr_* call goes through a guardrail layer before any network I/O: SQL is parsed with sqlglot and rejected unless it's a single SELECT/WITH...SELECT with no dangerous functions; CloudWatch calls are checked against a log-group allowlist, a time-window cap, and a bytes-scanned cost ceiling; NRQL is restricted to a single SELECT with no write-ish keywords and a clamped LIMIT. Results and any log messages are redacted before returning. See docs/design.md §6 for the full model.

Development

uv run ruff check .                              # lint
uv run pytest tests/unit -q                      # guardrail/redaction tests, no external deps
uv run pytest tests/integration -m integration   # requires a reachable Postgres; auto-skips otherwise

• tests/unit/ — pure logic, no network/DB dependency (the guardrail tests are the security-boundary tests and the highest priority in this suite).
• tests/integration/test_db_tools.py — runs against your configured Postgres; skipped automatically if it isn't reachable.

CI (.github/workflows/ci.yml) runs lint + both test suites on every push/PR to main/dev.

See CLAUDE.md for the architecture/layering conventions this codebase follows, and docs/tool-reference.md for how to add a new tool. Contributing a change? See CONTRIBUTING.md.

License

MIT