MCP server for AI agents

Optional Model Context Protocol layer that exposes EventOre control and data plane APIs to Cursor, Claude, and other MCP clients.

Three workloads: frontend, backend, optional MCP
Production layout: MCP is a third optional pod; it talks only to the backend API.

Role in the architecture

EventOre separates control plane (provider registration, UI cascade, no broker TCP) from data plane (connections, publish, subscribe, inspect). The MCP server is a thin agent adapter — it never embeds Kafka or MQTT clients. All broker I/O goes through the same backend delegates as the React UI.

AI client ── MCP (stdio or HTTP) ──► eventore-mcp ── REST/SSE ──► EventOre backend
                                              │
                    control plane ◄───────────┼───────────► data plane
                    /api/v1/control           │           /api/v1/connections
                                              ▼
                                         Brokers / cloud streams

See also Control & data plane and Architecture.

When to deploy MCP: Use it when agents need to probe brokers, publish test messages, or inspect Kafka lag without the web UI. Skip it if operators only use the console — fewer pods and less attack surface.

Package and transports

Source: mcp/eventore-mcp (Node 20+, TypeScript). Published image: ghcr.io/vijayptiwari/eventore-mcp.

VariableDefaultDescription
EVENTORE_API_URLhttp://localhost:8080/api/v1Backend API base (must include /api/v1)
MCP_TRANSPORTstdiostdio for Cursor/desktop; http for Kubernetes
MCP_PORT3100HTTP listen port when MCP_TRANSPORT=http
MCP_AUTH_TOKEN(unset)Optional Bearer token on /mcp (HTTP only; does not authenticate to backend)

Recommended agent workflow

  1. Read eventore://config or call eventore_get_config — deployment mode and controlPlane.uiCascade.
  2. Read eventore://control-plane or eventore_get_control_plane — confirm the target protocol is in activeProtocols.
  3. Use prompt eventore_discover for a full onboarding brief, or eventore_protocol_guide for broker URL hints.
  4. Data plane: eventore_create_connection → validate → list destinations → publish/consume/inspect.
  5. Admins only: control-plane eventore_register_provider / eventore_deregister_provider (requires ADMIN mode and ADMIN_BROKER_OPS).

MCP tools

Control plane

ToolAPIPurpose
eventore_get_control_planeGET /control/planeRevision, providers, UI cascade
eventore_list_providersGET /control/providersAll provider descriptors
eventore_get_providerGET /control/providers/{protocol}One provider metadata
eventore_get_provider_statusGET /control/providers/{protocol}/statusRegistration and routability
eventore_register_providerPOST .../registerRuntime register (ADMIN)
eventore_deregister_providerDELETE .../registerRuntime deregister (ADMIN)

Data plane — connections & messaging

ToolPurpose
eventore_get_configMode, allowed actions, modules, embedded control plane summary
eventore_list_connectionsList connection profiles
eventore_create_connectionCreate profile (protocol must be registered)
eventore_update_connectionUpdate profile fields
eventore_delete_connectionRemove profile and subscriptions
eventore_validate_connectionConnectivity test
eventore_list_destinationsTopics / queues / streams
eventore_publish_messageUnified publish
eventore_consume_messagesShort SSE sample (not WebSocket)
eventore_protocol_guidePer-protocol hints or NL protocol suggestion
eventore_quick_probeEphemeral create → validate → list → optional samples → delete

Data plane — inspect & Kafka admin

ToolPurpose
eventore_inspect_clusterCluster / broker metadata
eventore_inspect_consumer_groupsConsumer groups or Pulsar subscriptions
eventore_inspect_lagConsumer lag (Kafka)
eventore_inspect_searchTopic message search / sample
eventore_triage_incident0.3.0 development preview: heuristic broker, lag and DLQ diagnostics; failed or unsupported checks may be omitted
eventore_kafka_publishKafka produce with key/partition headers
eventore_kafka_create_topicCreate topic (ADMIN)
eventore_kafka_delete_topicDelete topic (ADMIN)
eventore_kafka_list_aclsList ACLs (ADMIN)

MCP resources

URIContent
eventore://architectureStatic map of planes, APIs, and tool groupings
eventore://configLive GET /config
eventore://control-planeLive GET /control/plane
eventore://providersLive provider list
eventore://connectionsLive connection profiles
eventore://protocol-guidesStatic connection/publish hints (all eight protocol types)

MCP prompts

Prompts return ready-to-run playbooks for agents:

Cursor configuration (stdio)

cd mcp/eventore-mcp && npm install && npm run build

Add to Cursor MCP settings (see mcp/eventore-mcp/cursor-mcp.json.example):

{
  "mcpServers": {
    "eventore": {
      "command": "node",
      "args": ["C:/path/to/eventore/mcp/eventore-mcp/dist/index.js"],
      "env": {
        "EVENTORE_API_URL": "http://localhost:8080/api/v1",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Docker & Helm (published artifacts)

CI publishes ghcr.io/vijayptiwari/eventore-mcp and chart oci://ghcr.io/vijayptiwari/charts/eventore-mcp. Full image/chart list: Published Docker images & Helm charts.

# Stack: backend + frontend + MCP
docker compose -f docker/docker-compose.stack.yml up -d

# Published MCP image only (backend elsewhere)
docker pull ghcr.io/vijayptiwari/eventore-mcp:0.2.1
docker run -p 3100:3100 -e MCP_TRANSPORT=http \
  -e EVENTORE_API_URL=http://host.docker.internal:8080/api/v1 \
  ghcr.io/vijayptiwari/eventore-mcp:0.2.1
helm install eventore oci://ghcr.io/vijayptiwari/charts/eventore --version 0.2.1 \
  -f deploy/helm/eventore/values-published.yaml

helm install eventore-mcp oci://ghcr.io/vijayptiwari/charts/eventore-mcp --version 0.2.1 \
  --set eventore.apiUrl=http://eventore-backend:8080/api/v1

HTTP health: GET :3100/health. MCP endpoint: POST/GET :3100/mcp (streamable HTTP).

Policy and security

Limitations

Related: Deployment · Control & data plane · mcp/eventore-mcp/README.md in the repository.