sensorium

Observability for agents: OpenTelemetry in, MCP out.

What it is

sensorium keeps the logs, traces and metrics of many services in one Postgres store and serves them to agents over MCP. There is no dashboard: the reader is an agent doing maintenance or analysis. It is open source under the MIT License.

What it does

Ingest
OpenTelemetry over HTTP, as JSON or protobuf, at /v1/logs, /v1/traces and /v1/metrics.
Projects
Each project has its own ingest token, and the token decides where its records land.
MCP
Eight read-only tools at /mcp: list_projects, query_logs, query_traces, list_traces, error_summary, top_sources, query_metrics and search.
Retention
Metrics for 14 days, spans and logs for 30, by default.

Deploy

  1. On any machine with Docker, fetch the compose file and the env example. Set POSTGRES_PASSWORD and SENSORIUM_MCP_TOKEN in .env.

    curl -fsSLO https://raw.githubusercontent.com/zyx1121/sensorium/main/compose.yaml
curl -fsSL -o .env https://raw.githubusercontent.com/zyx1121/sensorium/main/.env.example

  2. Start it. The receiver on port 8787, the MCP endpoint on port 8788 and a daily retention sweep come up from one image, beside Postgres.

    docker compose up -d

  3. Put a reverse proxy with TLS in front, and route /mcp to port 8788 and everything else to port 8787. Both ports listen on 127.0.0.1, and tokens travel in the Authorization header.

Use

  1. Register a project. The token is printed once, and running it again for the same name rotates it.

    docker compose run --rm ingest register-project my-service

  2. Point the service's OpenTelemetry exporter at sensorium. sensorium takes neither gzip nor gRPC. For an exporter that only speaks those, put an OpenTelemetry Collector in front and set compression: none on its otlphttp exporter.

    OTEL_EXPORTER_OTLP_ENDPOINT=https://sensorium.example.com
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer%20<ingest token>

  3. Connect an agent to the MCP endpoint.

    claude mcp add --transport http sensorium https://sensorium.example.com/mcp \
  --header "Authorization: Bearer <SENSORIUM_MCP_TOKEN>"

  4. Ask it what broke. error_summary and top_sources are the usual first calls.

Configure

Every setting is an environment variable in .env. POSTGRES_PASSWORD and SENSORIUM_MCP_TOKEN are required, and the SENSORIUM_RETENTION_*_DAYS keys set how long data stays. .env.example documents every key.