MCP server

VentStream ships a read-only MCP server: ventstream mcp. It lets AI agents — Claude Desktop, IDE assistants, support bots — query the documents your pipelines materialize in the sinks, without holding any source-database credentials. The server is part of the open-source engine binary. It needs nothing but your pipeline config and read-only sink credentials, and it never touches the source database: agents read the sink documents the pipeline keeps in sync within milliseconds.

The config

ventstream mcp takes the same pipeline config your engine already runs — usually the exact file, unchanged. From it the server learns three things: where the sink is (and its credentials), what the targets are, and what the documents look like (from the joins spec). A typical config:

pipeline.yaml — a typical pipeline config

# pipeline.yaml — the same file the CDC engine runs
schema_version: 1
roles: [cdc]

source:                    # ignored by the MCP server — it never reads the source
  kind: postgres
  postgres:
    host_ref: env:VS_PG_HOST
    port: 5432
    user_ref: env:VS_PG_USER
    password_ref: env:VS_PG_PASSWORD
    database_ref: env:VS_PG_DATABASE
    publication: shop_pub
    slot: shop_slot
    bootstrap: { mode: snapshot, chunk_size: 10000 }
    denormalize_mode: sql

sink:                      # what the MCP server reads
  kind: meilisearch
  meilisearch:
    endpoint_ref: env:VS_MEILI_ENDPOINT
    api_key_ref: env:VS_MEILI_API_KEY     # use a read-only key here
    index_prefix: "shop_"
    index_routing: { mode: by_projection_target }

specs:
  joins: joins.yaml        # defines the targets and document shapes

runtime:
  health_listen: 127.0.0.1:4043
  dlq_path: ./state/dlq.jsonl

joins.yaml — targets and document shapes

The joins spec is where targets get their names and the documents get their shape:

# joins.yaml
joins:
  - name: orders
    primary:
      table: public.orders
      pk: id
    related:
      - id: customer
        table: public.customers
        pk: id
        join_on: { from: customer_id, to: id }
        embed_as: customer
        cardinality: one
      - id: items
        table: public.order_items
        pk: id
        join_on: { from: id, to: order_id }
        embed_as: items
        cardinality: many
    target:
      index: orders        # ← this is the target name agents query

With this config the server exposes one target, orders, whose documents are orders with an embedded customer object and items array — and it serves that shape description to agents automatically. A complete runnable version of this setup — schema, seed data, configs, token flow, Claude wiring — lives in examples/mcp.

Run it

ventstream mcp --config pipeline.yaml

Serve several pipelines from one endpoint by repeating --config. Target names must be unique across the loaded configs:

ventstream mcp \
  --config pg-search.yaml \
  --config mongo-cache.yaml

The env vars referenced by the config (VS_MEILI_ENDPOINT, …) must be set for the MCP server too — give it read-only sink credentials rather than the writer’s.

Running as a role

The subcommand above is the interactive way. For supervised deployments — systemd, Kubernetes, or Fleet-managed — the engine can run the MCP server as a role, dispatched from the config itself with no CLI arguments:

schema_version: 1
roles: [mcp]               # mcp runs alone — never beside the cdc writer
sink:                      # required: what it reads
  kind: meilisearch
  meilisearch:
    endpoint_ref: env:VS_MEILI_ENDPOINT
    api_key_ref: env:VS_MEILI_API_KEY
    index_prefix: "shop_"
    index_routing: { mode: by_projection_target }
specs:
  joins: joins.yaml
runtime:
  health_listen: 0.0.0.0:4043     # /readyz for probes and supervisors
  mcp:
    listen: 0.0.0.0:8790
    keys_ref: env:VS_MCP_KEYS     # or auth_token_ref — required off loopback

VS_ENGINE_CONFIG=… ventstream (no arguments) boots the server, serves /readyz on the health listener, and shuts down cleanly on SIGTERM. An mcp-role config has no source: — it only ever reads the sink. Fleet-managed: apply the same YAML with ventstreamctl configurations apply --engine-config … — the control plane validates it and delivers it to the deployment like any pipeline config. The managed-agent chart supports workload.roles: mcp (under kind: realtime) with service.mcpPort exposing the listener, and ventstreamctl mcp keys generate mints tokens, printing the token once and the token_hash entry for your keys secret. Query traffic always goes straight from agents to the MCP deployment — never through the control plane.

Transports

stdio (default) — the MCP client spawns the process. A Claude Desktop entry looks like:

{
  "mcpServers": {
    "ventstream": {
      "command": "ventstream",
      "args": ["mcp", "--config", "/etc/ventstream/pipeline.yaml"],
      "env": { "VS_MEILI_API_KEY": "…" }
    }
  }
}

HTTP (--listen) — a shared endpoint for remote agents. Run one instance per environment next to your sinks; agents connect over the network and no sink credentials leave that deployment:

ventstream mcp \
  --config pipeline.yaml \
  --listen 0.0.0.0:8790 \
  --auth-token-ref env:VS_MCP_TOKEN

Clients POST MCP JSON-RPC to /mcp with Authorization: Bearer <token>; /healthz serves load-balancer checks. The server is stateless — no session ids — so replicas behind a plain load balancer need no session affinity. Security is enforced, not optional:

Binding a non-loopback address requires auth (--auth-token-ref or --keys-ref) — the server refuses to start without it.
Browser-origin requests are rejected unless allow-listed with --allow-origin (DNS-rebinding protection).
Request bodies cap at 1 MiB; tool dispatch times out at 30 s.
Run it behind TLS termination (your load balancer or reverse proxy).

Tokens and scoping

Mint a token with the built-in generator:

ventstream mcp generate-token --hash
# vsk_ubKSepNIb2…                ← give this to the agent
# sha256:473fe34c1…              ← paste this into keys.yaml

The simplest setup is one full-access token via --auth-token-ref env:VS_MCP_TOKEN. For per-agent control, use a keys file — each key is a named token restricted to the targets it may query:

keys:
  - name: support-bot
    token_hash: sha256:473fe34c1…   # hash at rest, plaintext never stored
    targets: [orders]               # this agent sees ONLY the orders target
  - name: ops-agent
    token_hash: sha256:9c01d22ab…
    targets: all

ventstream mcp --config pipeline.yaml \
  --listen 0.0.0.0:8790 --keys-ref file:/etc/ventstream/keys.yaml

A scoped key’s world shrinks to its targets: list_targets and resources list only them, and querying anything else returns the same error as a target that does not exist — a scoped agent cannot discover what it is not allowed to see. Every request is logged with its key name for attribution. Revoke a key by removing it from the file and restarting (or rolling the deployment).

Tools

Tool	Arguments	What it does
`list_targets`	—	Every target with its sink kind and document shape
`get_entity`	`target`, `pk`	O(1) fetch of one document by primary key
`search`	`target`, `query`, `limit?`	Full-text search (OpenSearch / Elasticsearch / Meilisearch targets)
`scan`	`target`, `pattern`, `limit?`	Glob scan of doc ids (Redis targets)

pk accepts a scalar or an array for composite keys. Values are normalized exactly like the writer normalizes them, so 100 and "100" find the same document.

{ "name": "get_entity", "arguments": { "target": "orders", "pk": 100 } }

returns the full joined document — parent row plus embedded relations — straight from the sink. Each target is also exposed as an MCP resource at vs://targets/{name} describing its document shape (primary table, key columns, embedded relations and their cardinality), derived from your joins spec. Agents read it to learn what the documents look like before querying.

How keys resolve

Doc ids and sink keys are deterministic, and the server links the same encoder code the sinks use when writing — Redis keyspace, Meilisearch primary keys, OpenSearch ids. A read key is byte-identical to the written key by construction. Target enumeration follows your sink routing:

fixed — the configured target or index.
views (Redis) — one target per view.
by_projection_target — one target per join target.index.
by_output_relation — targets are not derivable from config; pass them explicitly with --target <name> (repeated).

Guardrails

Use read-only sink credentials in the config you give the server — it only ever issues reads, but the credential should enforce it too.
--allow-target <name> (repeated) restricts the served targets; anything else behaves as unknown.
--max-results <n> caps search/scan result sizes (default 50, hard max 500).

Notes

A degraded pipeline does not stop reads — agents see whatever the sink currently holds. Watch pipeline health to know how fresh that is.
Server-initiated SSE streams are not offered: every tool is a short single-shot read, answered as plain JSON.

Get started

Concepts

Connectors

Guides

Engineering

VentStream Cloud

Deploy

Reference

The config

Run it

Running as a role

Transports

Tokens and scoping

Tools

How keys resolve

Guardrails

Notes

​The config

​Run it

​Running as a role

​Transports

​Tokens and scoping

​Tools

​How keys resolve

​Guardrails

​Notes

The config

Run it

Running as a role

Transports

Tokens and scoping

Tools

How keys resolve

Guardrails

Notes