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-compose.ps1 -SeqUrl "http://localhost:10150" -SeqApiKey "<YOUR_SEQ_API_KEY>" -Build

Bash:

./scripts/run-mcp-compose.sh --seq-url "http://localhost:10150" --seq-api-key "<YOUR_SEQ_API_KEY>" --build

Compose run behavior:

• Value precedence is: explicit script args -> existing environment variables -> .env.

• If the target .env is missing, scripts create a generic template .env automatically.

• When that generated generic template is in use, ensure SEQ_URL and SEQ_API_KEY are resolved via script args, existing environment variables, or a populated .env file.

• MCP_IMAGE_TAG is optional; when empty, Compose uses an untagged image reference (mcp/seq-otel).

• Scripts check image availability through compose service metadata and auto-build if the selected tag is not available.

• By default, no container name is specified, so Docker auto-generates a random name.

• You can override container name with -ContainerName (PowerShell) or --container-name (Bash).

• For security, prefer setting SEQ_API_KEY via environment variables or .env instead of CLI args.

Or use helper scripts:

PowerShell:

./scripts/build-image.ps1

Bash:

./scripts/build-image.sh

Build and push to registry (pullable by other Docker hosts):

PowerShell:

./scripts/build-image.ps1 -Registry ghcr.io/mclifeleader -Tag v0.3.1 -Push

Bash:

./scripts/build-image.sh --registry ghcr.io/mclifeleader --tag v0.3.1 --push

The build scripts apply :latest by default alongside any explicit version tag. To disable this behavior, pass an empty latest-tag value (PowerShell: -LatestTag ""; Bash: --latest-tag "").

Build and export tar (loadable with docker load):

PowerShell:

./scripts/build-image.ps1 -SaveTar ./mcp-seq-otel.tar

Bash:

./scripts/build-image.sh --save-tar ./mcp-seq-otel.tar

Run against local Seq:

docker run --rm -i \
  -e SEQ_URL=http://host.docker.internal:10150 \
  -e SEQ_API_KEY=your-key \
  mcp/seq-otel

Run against FQDN Seq:

docker run --rm -i \
  -e SEQ_URL=https://seq.example.com \
  -e SEQ_API_KEY=your-key \
  mcp/seq-otel

Run with Podman:

podman build -t mcp/seq-otel .
podman run --rm -i \
  -e SEQ_URL=https://seq.example.com \
  -e SEQ_API_KEY=your-key \
  mcp/seq-otel

The container startup contract requires both variables to be present:

• SEQ_URL

• SEQ_API_KEY

If either is missing, the container exits immediately with a clear startup error.

Copy/Paste MCP Config (Codex and VS Code)

Assumes the image already exists (mcp/seq-otel).

{
  "mcpServers": {
    "seq-otel": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "SEQ_URL=http://host.docker.internal:10150",
        "-e",
        "SEQ_API_KEY=<YOUR_SEQ_API_KEY>",
        "mcp/seq-otel"
      ]
    }
  }
}

Docker MCP Catalog Compatibility

This repo includes a catalog-ready server definition in:

• catalog/server.yaml

• catalog/tools.json

• assets/seq-otel-icon.svg

catalog/server.yaml declares:

• SEQ_URL as a required user parameter (mapped via config.env)

• SEQ_API_KEY as a required secret (mapped via config.secrets)

These files follow the Docker MCP registry server format, so they can be used in catalog generation/import workflows (for example via docker/mcp-registry tools).

Submission checklist for Docker MCP Registry:

• docs/docker-mcp-registry-submission.md

MCP Client Integration Example

Use a command-based MCP client entry that launches the container with stdin/stdout attached.

{
  "mcpServers": {
    "seq-otel": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "SEQ_URL=https://seq.example.com",
        "-e",
        "SEQ_API_KEY=<YOUR_SEQ_API_KEY>",
        "mcp/seq-otel"
      ]
    }
  }
}

Security Notes

• Do not commit keys.

• Use least-privilege Seq API keys.

• Prefer HTTPS for non-local Seq instances.

API Mapping Artifact

• Full generated API map: docs/api-map.md

• Maintenance/update playbook: docs/seq-mcp-maintenance.md

• Project skill for update workflows: .github/skills/seq-mcp-maintainer/SKILL.md

• Project wiki (how-to and operations): https://github.com/MCLifeLeader/seq-mcp/wiki

Status

Core standalone server scaffold is implemented and buildable.