Seq MCP Server

mcp-seq-otel

Standalone MCP server that gives AI agents controlled API access to a user-owned Datalust Seq instance.

What This Service Assumes

• You already run/manage your own Seq instance.
• This service only needs connection settings.

Required configuration:

• SEQ_URL
• SEQ_API_KEY

URL Support

SEQ_URL accepts either:

• Host URL (recommended; service will append /api):
  • http://localhost:10150
  • https://seq.example.com
• Full API base URL (also supported):
  • http://localhost:10150/api
  • https://seq.example.com/api

Available MCP Tools

• seq_connection_test: validates Seq connectivity and API reachability, and reports the resolved root /health URL used for the check.
• seq_starter_help: lists the compact starter alias tools.
• seq_starter_overview: quick health, user, diagnostics, signals, and workspace summary.
• seq_starter_events_search: common event search by filter/signal/time range.
• seq_starter_event_by_id: fetch one event by id.
• seq_starter_data_query: run a q query using GET or POST.
• seq_starter_signals_list / seq_starter_signal_by_id: signal discovery helpers.
• seq_starter_dashboards_list: list dashboards.
• seq_starter_alerts_list: list alerts.
• seq_starter_events_stream: bounded live-tail style stream call.
• seq_api_catalog: returns the full official Seq route/verb/permission catalog.
• seq_api_live_links: discovers live name -> route links from your Seq instance.
• seq_api_request: generic verb/path invoker for any Seq API route.
• seq_<verb>_<route>: auto-generated tool per official route+verb (from docs).

Scope note:

• seq_starter_* tools are focused on common read workflows.
• seq_api_request and seq_<verb>_<route> expose the broader HTTP API surface from the Seq endpoint catalog, including non-GET routes.

Seq API Key Permissions

Use least privilege based on the exact tools/workflows your MCP client will call.

Authoritative Datalust references:

• API keys and permission model: https://docs.datalust.co/docs/api-keys
• HTTP API usage guide: https://docs.datalust.co/docs/using-the-http-api
• Server endpoint + permission table: https://docs.datalust.co/docs/server-http-api

Recommended permission profiles:

• Read-focused starter usage (seq_starter_*, seq_connection_test, read-only queries): enable Read; disable Ingest, Write, Project, Organization, System.
• Full route-surface usage (seq_api_request and seq_<verb>_<route>): required permissions depend on the specific route+verb; check seq_api_catalog or the official endpoint table before granting.

Permission guidance for this project:

Starter endpoint mapping in current implementation:

• GET /health: public endpoint.
• GET /api/events/resources: public endpoint.
• GET /api/events: Read permission demand.
• GET /api/events/{id}: Read permission demand.
• GET /api/data: Read permission demand.

API Key Header

The server authenticates to Seq using the X-Seq-ApiKey header.

Resilience and Permission Handling

Tool failures are returned as structured MCP error responses (isError: true) instead of crashing the server process.

Current graceful handling includes:

• 401 Unauthorized: returns guidance to verify SEQ_API_KEY and SEQ_URL.
• 403 Forbidden: returns a permission-denied response with route-derived permission hints when available.
• Network/timeout failures: returns connectivity diagnostics for AI clients.

Health check behavior:

• seq_connection_test always probes the Seq host root at /health.
• If SEQ_URL is configured as either http://host:port or http://host:port/api, the health check resolves to http://host:port/health.

Local Run (Node)

Node.js requirement: LTS (see .nvmrc).

npm install
npm run build

Windows PowerShell:

$env:SEQ_URL = "http://localhost:10150"
$env:SEQ_API_KEY = "your-key"
node dist/index.js

Docker Standalone Run

Docker Hub documentation assets in this repo:

• Auto-sync source for Hub long description: `.dockerhub-readme.md`
• Main project reference: `README.md`

Build image:

docker build -t mcp/seq-otel .

Run via Docker Compose (recommended for MCP stdio):

PowerShell:

./scripts/run-mcp-