Seq API访问MCP服务器

mcp-seq-otlp

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

Official Seq API Docs

• Official Seq HTTP API usage guide: Using the HTTP API

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_agent_guide: returns agent-focused tool selection rules, recommended workflows, examples, and safety limits.
• 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 official cataloged Seq API routes.
• seq_server_ttl: report remaining idle lifetime without resetting the timer.
• seq_server_keep_alive: reset the idle timer without contacting Seq.
• 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.
• Generic requests are constrained to official route templates, with bounded query/path maps and request/response size limits to reduce accidental high-cost calls.

Agent Usage Process

AI agents should follow this sequence for reliable use:

1. Start with seq_agent_guide to get the current workflow guidance and example calls.
2. Use seq_connection_test if the target Seq instance, API key, or URL shape may be wrong.
3. Use seq_starter_overview to understand the current user, diagnostics status, and visible signals/workspaces.
4. Prefer seq_starter_events_search, seq_starter_data_query, and other seq_starter_* tools for common read workflows.
5. For advanced API access, call seq_api_catalog first, then call seq_api_request with the exact official route template.

Short examples:

{
    "tool": "seq_starter_events_search",
    "arguments": {
        "filter": "@Level = 'Error'",
        "count": 50,
        "render": true
    }
}

{
    "tool": "seq_api_request",
    "arguments": {
        "method": "GET",
        "path": "api/events/{id}",
        "pathParams": {
            "id": "event-123"
        },
        "query": {
            "render": "true"
        }
    }
}

Detailed agent workflow guide:

• docs/agent-workflows.md

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: Datalust API Keys
• HTTP API usage guide: Using the HTTP API
• Server endpoint + permission table: 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.
• Oversized requests/responses: returns actionable limit errors instead of exhausting the server process.
• Binary responses: returns structured metadata with base64 payloads for non-text endpoints such as icon routes.

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)

Use Node.js v24.21.0 LTS and npm 12.2.0 (see .nvmrc and package.json). Install the pinned npm version after selecting Node.js:

npm install --global npm@12.2.0
npm ci
npm run build
npm test
npm audit

The Docker build and CI use the same npm version. Both Docker stages pin the Node.js 24.21.0 / Alpine 3.24 image by digest for reproducible builds.

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 and refresh local MCP catalog artifacts:

./build-docker-image.sh

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-otlp).
• 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:

./build-docker-image.ps1

Bash:

./build-docker-image.sh

Script intent:

• ./build-docker-image.sh: generates Docker MCP Toolkit manifests, builds and validates the Docker image, and refreshes the local Docker MCP catalog when Docker MCP is available.
• ./build-docker-image.ps1: generates Docker MCP Toolkit manifests, builds and validates the Docker image, and refreshes the local Docker MCP catalog when Docker MCP is available.
• ./scripts/run-mcp-compose.sh: runs the MCP server through Docker Compose for stdio use; it can build if needed, but its primary job is to run the container.

Default build behavior:

• When you run the build script without --tag or -Tag, it builds the named image mcp/seq-otlp, which Docker treats as mcp/seq-otlp:latest.
• If you want a different reusable image such as mcp/seq-otlp:v0.4.1, pass an explicit tag.
• --latest-tag or -LatestTag remains optional and adds an additional tag alongside the primary image tag.
• To skip local Docker MCP catalog refresh, pass -SkipDockerMcpCatalogInstall in PowerShell or --skip-docker-mcp-catalog-install in Bash.

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

PowerShell:

./build-docker-image.ps1 -Registry ghcr.io/mclifeleader -Tag v0.4.1 -Push

Bash:

./build-docker-image.sh --registry ghcr.io/mclifeleader --tag v0.4.1 --push

By default, the build scripts do not apply an additional tag. If you want one, pass it explicitly with PowerShell -LatestTag <tag> or Bash --latest-tag <tag>.

Build and export tar (loadable with docker load):

PowerShell:

./build-docker-image.ps1 -SaveTar ./mcp-seq-otlp.tar

Bash:

./build-docker-image.sh --save-tar ./mcp-seq-otlp.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-otlp

Run against FQDN Seq:

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

Run with Podman:

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

The container startup contract requires both variables to be present:

• SEQ_URL
• SEQ_API_KEY

Optional stability controls:

• MCP_IDLE_TIMEOUT_MS: idle lifetime in milliseconds, default 900000 (15 minutes), bounded to 1-2147483647.
• SEQ_TIMEOUT_MS: request timeout in milliseconds, default 30000, bounded to 1000-120000.
• SEQ_MAX_REQUEST_BYTES: max outbound request body size, default 262144.
• SEQ_MAX_RESPONSE_BYTES: max inbound response size, default 1048576.

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

Container lifecycle

The server automatically stops after 15 minutes without an MCP request. Set MCP_IDLE_TIMEOUT_MS to configure this interval. The timer starts at server startup. Every MCP request resets it, including discovery, ping, and failed tool calls, except seq_server_ttl. Protocol notifications and outgoing responses do not reset it. Expiry closes the transport and exits successfully, even if stdin is still open or a Seq request is outstanding; outstanding calls may be interrupted.

• seq_server_ttl returns { idleTimeoutMs, remainingMs } without resetting the timer.
• seq_server_keep_alive resets the timer and returns the same fields, without contacting Seq.

This is a stdio MCP server; these endpoints are MCP tools. The server also exits when stdin reaches EOF and handles SIGTERM/SIGINT as graceful shutdown requests. The launcher must use --rm so Docker or Podman removes the container after the server process exits:

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

Use the same flags with podman run. Expiry stops the container and removes it from the active container list. --rm also removes the stopped container record; the image remains available for new containers. Avoid restart policies such as always or unless-stopped, which would relaunch an expired container.

For Compose, use docker compose run --rm -i seq-otlp-mcp or one of the provided run-mcp-compose scripts. Do not use docker compose up -d for this stdio server: detached mode has no MCP client attached to close stdin.

There is no image or MCP catalog setting that can force Docker to remove a container. Removal is intentionally controlled by the Docker/MCP host. The container does not mount the Docker socket and cannot safely delete itself.

If an instance lingers:

• running with OpenStdin=true: the launcher still owns an open stdin stream. The server exits when the idle timer expires; MCP requests such as periodic pings reset that timer. Close stdin or stop the container for immediate shutdown.
• exited: the launcher omitted --rm and must remove the stopped container.

The Docker MCP Gateway normally supplies --rm -i --init for catalog-based stdio servers. A lingering per-server container under that launcher indicates a gateway/session cleanup issue rather than an image metadata option.

Live contract check:

npm run validate:live-contract

This command uses the current SEQ_URL and SEQ_API_KEY to compare live advertised routes against src/route-catalog.ts and to probe safe read-only endpoints for stale 404 entries.

Copy/Paste MCP Config (Codex and VS Code)

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

{
    "mcpServers": {
        "seq-otlp": {
            "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-otlp"
            ]
        }
    }
}

Docker MCP Catalog Compatibility

This repo includes a catalog-ready server definition in:

• catalog/server.yaml
• catalog/tools.json
• catalog/docker-mcp-toolkit.yaml
• assets/seq-otlp-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)

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

catalog/docker-mcp-toolkit.yaml is a Docker MCP Toolkit local import entry for docker mcp catalog server add / docker mcp profile server add workflows. It is generated by ./build-docker-image.ps1 and ./build-docker-image.sh from catalog/tools.json, then included in the built image.

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-otlp": {
            "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-otlp"
            ]
        }
    }
}

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): seq-mcp wiki

Status

Core standalone server scaffold is implemented and buildable.