> For the complete documentation index, see [llms.txt](https://docs.deltastream.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.deltastream.io/how-do-i.../expose-a-materialized-view-over-mcp.md).

# Connect AI Agents to DeltaStream with MCP

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard that lets AI agents discover and call tools exposed by a server. DeltaStream runs a built-in MCP server on its API endpoint, so any MCP-compatible client (Claude, Cursor, OpenAI Agent Builder, custom agents, and so on) can query materialized views, run DeltaStream SQL, and search this documentation.

## Overview

* **Endpoint:** `https://<API_ENDPOINT_HOSTNAME>/mcp/v2`. To find your API endpoint hostname, see [Call DeltaStream's REST API](https://docs.deltastream.io/how-do-i.../call-deltastreams-rest-api.md).
* **Transport:** MCP Streamable HTTP. The server is stateless and returns JSON responses (no server-sent event streams).
* **Authentication:** Every request must include `Authorization: Bearer <API_TOKEN>`. Requests without it receive `401 Unauthorized`.
* **Authorization:** Tool calls run as the role bound to the API token, so DeltaStream RBAC governs what the agent can see and do.
* **Enablement:** No configuration is needed. The endpoint is available to every organization.

## Available tools

The server exposes the same fixed set of tools to every client. Materialized views are **not** exposed as individual tools; agents use `query_mview` to query them.

| Tool                   | Read-only | Purpose                                               |
| ---------------------- | --------- | ----------------------------------------------------- |
| `query_mview`          | Yes       | Run a SQL `SELECT` against materialized views.        |
| `execute_dsql`         | No        | Run any DeltaStream SQL statement.                    |
| `doc_search`           | Yes       | Search the DeltaStream documentation.                 |
| `read_skill_reference` | Yes       | Return a built-in DeltaStream SQL reference document. |

### query\_mview

Runs a SQL `SELECT` against materialized views. Materialized views are stored in ClickHouse, so this tool uses **ClickHouse SQL dialect**, not DeltaStream SQL.

| Parameter      | Required | Description                                                                                                                             |
| -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `sql`          | Yes      | ClickHouse-compatible `SELECT`. Use fully qualified, double-quoted names, for example `SELECT * FROM "mydb"."public"."my_mv" LIMIT 10`. |
| `organization` | No       | Organization UUID. If omitted, the organization bound to the API token is used.                                                         |
| `role`         | No       | Role name to run the query as. If omitted, the token's role is used.                                                                    |

Behavior:

* Results are returned as `{"columns": [...], "rows": [[...], ...]}`, both as text content and as structured content matching the tool's output schema.
* Responses are capped at 128 KB of JSON. Rows past the cap are dropped, so always include a `LIMIT` and use `LIMIT`/`OFFSET` to paginate.
* Decimal values are returned as strings to preserve precision. 64-bit integers outside the JSON-safe range (±2^53−1) are also returned as strings.
* To discover materialized views and their columns, query the system tables:

  ```sql
  SELECT * FROM deltastream.sys."relations" WHERE type = 'materialized_view' LIMIT 100;
  SELECT * FROM deltastream.sys."relation_columns" WHERE relation_name = 'my_mv' LIMIT 100;
  ```

### execute\_dsql

Runs any DeltaStream SQL statement: DDL (`CREATE`, `DROP`), metadata commands (`LIST`, `DESCRIBE`), `USE`, `TERMINATE`, pipeline launches (`INSERT INTO`, `CREATE STREAM AS`, `CREATE CHANGELOG AS`, `CREATE MATERIALIZED VIEW AS`, applications), and `SELECT` or `PRINT` against streaming relations.

| Parameter                             | Required | Description                                                                                                                                                                                                                                                                                                                                      |
| ------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `sql`                                 | Yes      | The DeltaStream SQL statement to run.                                                                                                                                                                                                                                                                                                            |
| `organization`                        | No       | Organization UUID. If omitted, the organization bound to the API token is used. Non-UUID values are ignored.                                                                                                                                                                                                                                     |
| `database`, `schema`, `store`, `role` | No       | Session context for this call.                                                                                                                                                                                                                                                                                                                   |
| `compute_pool`                        | No       | Only for batch queries that read `TABLE` relations in Iceberg or Databricks stores. Omit for streaming queries and sandbox `SELECT`/`PRINT`.                                                                                                                                                                                                     |
| `attachments`                         | No       | Map of bare filename to base64-encoded file contents, for statements that reference `@file` values, for example `CREATE DESCRIPTOR_SOURCE foo WITH ('file' = '@employee.pb')` with `{"employee.pb": "<base64>"}`.                                                                                                                                |
| `require_confirmation`, `confirmed`   | No       | Optional confirmation gate. When `require_confirmation` is `true` and the statement mutates resources (`CREATE`, `DROP`, `ALTER`, `INSERT INTO`, `TERMINATE`, `START`, `STOP`, `GRANT`, `REVOKE`), the tool returns a `confirmation_required` payload instead of executing unless `confirmed` is also `true`. Most MCP clients should omit both. |

Behavior:

* Returns up to **200 rows** as `{"rows": [...], "context": {...}}`. The `context` object reports the organization, database, schema, store, role, and compute pool in effect after the statement ran.
* Session context does **not** persist between calls. Pass context parameters on every call, or use fully qualified `database.schema.relation` names.
* Streaming statements such as `PRINT` or `SELECT` on a stream are sampled for up to **30 seconds**. The response then includes a `note` field describing the sample.

### doc\_search

Searches this documentation site and returns matching pages. Takes a single required `query` string.

### read\_skill\_reference

Returns a built-in reference document with canonical DeltaStream SQL templates and patterns. Agents should call it before writing complex DDL or queries. Takes a required `reference_name`, one of: `databases`, `namespaces`, `stores`, `relations`, `generation-sampling`, `query-patterns`.

## Set up access for an agent

{% hint style="warning" %}
`execute_dsql` can run any statement the token's role is permitted to run, including `CREATE`, `DROP`, and `TERMINATE`. Bind agent tokens to a dedicated, least-privilege role, never to `sysadmin` or `orgadmin`.
{% endhint %}

1. **Create the materialized views** you want the agent to read. See [Create and Query Materialized Views](https://docs.deltastream.io/how-do-i.../creating-and-querying-materialized-views.md).
2. **Create a role for the agent** and grant only what it needs. For read-only access to one materialized view `myview` in `mydb.public`:

   ```sql
   USE ROLE orgadmin;
   CREATE ROLE ai_agent;
   GRANT USAGE ON DATABASE mydb TO ROLE ai_agent;
   GRANT USAGE ON SCHEMA public TO ROLE ai_agent;
   GRANT SELECT ON mydb.public.myview TO ROLE ai_agent;
   ```
3. **Create an API token bound to that role:**

   ```sql
   CREATE API_TOKEN myagent_token WITH ('token.role_name' = ai_agent);
   ```
4. **Verify the endpoint.** List the available tools:

   ```bash
   curl -X POST https://<API_ENDPOINT_HOSTNAME>/mcp/v2 \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -H "Authorization: Bearer <API_TOKEN>" \
     -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}'
   ```

   The response lists the four tools described above. Then query your view:

   ```bash
   curl -X POST https://<API_ENDPOINT_HOSTNAME>/mcp/v2 \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -H "Authorization: Bearer <API_TOKEN>" \
     -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "query_mview", "arguments": {"sql": "SELECT * FROM \"mydb\".\"public\".\"myview\" LIMIT 10"}}}'
   ```

## Connect an MCP client

Configure your client to use a remote MCP server over HTTP with the endpoint URL and an `Authorization` header. For example:

* **Claude Code:**

  ```bash
  claude mcp add --transport http deltastream https://<API_ENDPOINT_HOSTNAME>/mcp/v2 \
    --header "Authorization: Bearer <API_TOKEN>"
  ```
* **Clients that use a JSON config** (for example, Cursor):

  ```json
  {
    "mcpServers": {
      "deltastream": {
        "url": "https://<API_ENDPOINT_HOSTNAME>/mcp/v2",
        "headers": { "Authorization": "Bearer <API_TOKEN>" }
      }
    }
  }
  ```
* **OpenAI Agent Builder:** Add an MCP server with the endpoint URL and provide the API token as the bearer token.

## Security recommendations

* Use a dedicated role per agent and grant only the privileges it needs.
* Rotate API tokens regularly and drop tokens that are no longer used.
* If an agent should never modify resources, do not grant its role any `CREATE`, `DROP`, or ownership privileges. RBAC, not the tool list, is what restricts `execute_dsql`.

## Limitations

* Only tools are supported. The server does not expose MCP resources or prompts.
* The server is stateless, so it does not send server-initiated requests or notifications (sampling, roots, elicitation, progress).
* `query_mview` responses are capped at 128 KB, and `execute_dsql` returns at most 200 rows.
