opampserver

A Python implementation of an OpAMP (Open Agent Management Protocol) server, built on FastAPI and the official protobuf message definitions from open-telemetry/opamp-spec. It supports both transports the spec defines (WebSocket and plain HTTP) on a single endpoint, and covers status reporting, remote config delivery, and health reporting.

Feature scope

Implemented:

• ReportsStatus — sequence-number tracking and gap detection (asks the agent to resend full state via ReportFullState when a gap is detected)
• Remote config delivery (AcceptsRemoteConfig / ReportsEffectiveConfig / ReportsRemoteConfig) — config is resolved per-agent from YAML templates or a per-instance override, and only re-sent when its hash differs from what the agent has already applied
• ReportsHealth — parses and stores ComponentHealth, including nested sub-component health
• Partial/compressed status messages — fields the agent omits (per the spec's status-compression rules) don't overwrite previously known values
• A small admin REST API for operators (list agents, inspect one — with optional decoded config — set/clear a per-instance config override; pushed immediately if the agent is connected over WebSocket)

Out of scope for v1 (candidates for future work):

• Package/binary updates (AcceptsPackages, PackagesAvailable)
• Connection-settings management and the certificate/CSR flow (AcceptsOpAMPConnectionSettings, TOFU, agent-initiated CSR signing)
• ServerToAgentCommand (restart), custom messages/capabilities, ReportsAvailableComponents, heartbeat handling

Project layout

opampserver/
  proto/                # vendored opamp-spec .proto files + generated protobuf stubs
  models.py              # protobuf <-> plain-dict conversion helpers
  connection.py          # Connection abstraction (WebSocket vs. one-shot HTTP) + ConnectionManager
  registry.py             # per-message bookkeeping: sequence gaps, instance_uid assignment, merging
  config_engine.py        # remote config resolution (templates + overrides) and hash-diffing
  health.py                # ComponentHealth tree summarization
  pipeline.py               # shared registry -> config-engine processing used by both transports
  storage/
    schema.sql               # SQLite schema (agents, agent_configs)
    repository.py             # async SQLite repository
  transport/
    http.py                    # plain-HTTP transport (gzip, content-type, size limits)
    ws.py                       # WebSocket transport
  admin_api.py                  # operator-facing REST API
  app.py                         # FastAPI app wiring
  main.py                        # uvicorn entrypoint
opampserver_mcp/           # standalone MCP server exposing the admin API as LLM tools
  client.py                # async httpx client for the admin API + error mapping
  server.py                # FastMCP server with the 4 tools
  main.py                  # CLI entrypoint (opampserver-mcp)
scripts/gen_proto.sh      # regenerates protobuf stubs from the vendored .proto sources
config/templates.yaml      # default/group remote-config templates
tests/                     # unit + integration tests

Setup

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

If you bump the pinned open-telemetry/opamp-spec commit in scripts/gen_proto.sh, re-run it to regenerate the protobuf stubs:

bash scripts/gen_proto.sh

Running the server

uvicorn opampserver.app:app --host 127.0.0.1 --port 4320
# or: python -m opampserver.main

Bind to 127.0.0.1 explicitly if another process (e.g. Docker) is already listening on port 4320 over IPv6 — otherwise curl http://localhost:4320/... may hit the wrong listener while agents using 127.0.0.1 reach this server fine.

The server listens for both HTTP POST and WebSocket connections on /v1/opamp. By default it stores agent state in opampserver.sqlite3 and loads remote config templates from config/templates.yaml (both relative to the working directory); override either with:

OPAMPSERVER_DB_PATH=/path/to/state.sqlite3 \
OPAMPSERVER_CONFIG_PATH=/path/to/templates.yaml \
uvicorn opampserver.app:app --port 4320

Trying it out

Point a real agent at it — e.g. an OpenTelemetry Collector with the opamp extension configured against ws://localhost:4320/v1/opamp — or send a raw HTTP request with a serialized AgentToServer protobuf message and Content-Type: application/x-protobuf.

Admin API

The admin API has no authentication. Bind the server to 127.0.0.1 for local use only, or place it behind your own auth/proxy if exposed beyond localhost.

Read-only endpoints return agent state from SQLite. Config file bodies are base64-encoded (body_b64) by default; pass ?decode=true to get plain-text body instead (UTF-8, with invalid bytes replaced).

Method	Path	Description
GET	/api/agents	List all known agents
GET	/api/agents/{instance_uid}	Get one agent
PUT	/api/agents/{instance_uid}/config	Set a per-instance config override
DELETE	/api/agents/{instance_uid}/config	Clear the override

Query parameters for GET:

• decode (bool, default false) — when true, replace body_b64 with decoded body in effective_config.

Examples:

# List instance UIDs only
curl -s http://127.0.0.1:4320/api/agents | jq -r '.[].instance_uid'

# Full agent record (config still base64)
curl -s http://127.0.0.1:4320/api/agents/<instance_uid>

# Human-readable effective config (OTel Collector uses "" as the config key)
curl -s "http://127.0.0.1:4320/api/agents/<instance_uid>?decode=true" \
  | jq -r '.effective_config[""].body'

# Push a per-instance override (body is plain text in the request)
curl -X PUT http://127.0.0.1:4320/api/agents/<instance_uid>/config \
  -H "Content-Type: application/json" \
  -d '{"files": {"config.yaml": {"body": "receivers:\n  otlp: {}\n", "content_type": "text/yaml"}}}'

# Remove override (agent falls back to template on next poll)
curl -X DELETE http://127.0.0.1:4320/api/agents/<instance_uid>/config

Use 127.0.0.1 rather than localhost when testing from the same machine if port 4320 is shared with another IPv6 listener.

MCP server

opampserver_mcp/ is a standalone MCP server that exposes the admin API as tools for LLM clients (Claude Code, Claude Desktop, or any MCP-capable client). It's a separate process that talks to the OpAMP server over its REST API — no changes to, or imports from, the opampserver package.

Tools: list_agents (compact summaries), get_agent (full detail, config decoded by default), set_agent_config (validates YAML client-side before pushing; reports whether the config was delivered immediately over WebSocket), delete_agent_config (agent falls back to templates).

Install and run (the OpAMP server must be running):

pip install -e ".[mcp]"

# stdio transport (default — for local clients that spawn the server)
opampserver-mcp

# streamable HTTP transport — endpoint at http://127.0.0.1:4321/mcp
opampserver-mcp --transport http --port 4321

# point at a non-default OpAMP server
opampserver-mcp --opamp-url http://otherhost:4320

Flags have env-var equivalents: OPAMP_MCP_TRANSPORT, OPAMP_BASE_URL, OPAMP_MCP_HOST, OPAMP_MCP_PORT.

Register in Claude Code:

# stdio
claude mcp add opamp -- /path/to/confOpAmpMCP/.venv/bin/opampserver-mcp
# or HTTP (start opampserver-mcp --transport http first)
claude mcp add --transport http opamp http://127.0.0.1:4321/mcp

Register in Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "opamp": {
      "command": "/path/to/confOpAmpMCP/.venv/bin/opampserver-mcp"
    }
  }
}

Example prompts once connected: "List all OpAMP agents and their health", "Show the effective config for the agent named otelcol", "Push a config to agent <uid> that enables the OTLP gRPC receiver", "Reset agent <uid> back to the template config".

Testing

pytest -q

32 tests cover: AgentRegistry sequence-gap detection and partial-message merging, config-engine template/group/override resolution and hash-diffing, health-tree summarization, admin API decode flag behavior, full integration round trips over both HTTP and WebSocket (including a live admin-triggered config push), and the MCP server tools (invoked through a real in-memory MCP client session against the in-process FastAPI app).