M↓ View as Markdown ↗

Actian MCP Server for Zen¶

Connect the MCP-compatible client to Actian Zen using the Actian MCP Server. The server handles automatic Zen dialect translation, allowing you to explore schema metadata, execute SQL queries, and perform ORM operations through a standard interface.

Writes are disabled by default. Setting query_mode to read-write enables them and changes which tools the server registers — see Write support and Tools.

Capabilities¶

The Actian MCP Server for Zen supports the following operations:

Action	Description
Run SQL queries	Execute `SELECT` with automatic translation to Zen dialect.
List tables and views	Discover available objects and inspect their structures.
ORM operations	Query data using `JOIN`, `WHERE`, `ORDER BY`, and `LIMIT` clauses.
Write data	`INSERT`, `UPDATE`, `DELETE`, and `MERGE`, when `query_mode` is `read-write`. A conditional write states how many rows currently match before it is approved.
Blob and file data	List and download blob or file data stored in the database. Read-only mode.
Server management	Query server capabilities, list DSNs, and release locks. Read-only mode.
Schema metadata	View the database schema as a structured resource.

Prerequisites¶

Before starting the server, ensure the following requirements are met:

Container Engine: Docker installed and running on the host machine.
Actian Zen Instance: A running instance that the container can reach.
Credentials (Optional): Required if the Zen database uses authentication.
OIDC provider (Optional): Required if you are using OAuth authentication.

Configuration¶

You can configure the MCP Server for Zen using a conf.json file. Mount this file into the container at /app/conf.json. Choose one of the two connection formats below based on the security requirements (credentials).

Connection Formats¶

DSN connection (no credentials)

Use this format when the built-in is odbc.ini and DSN is sufficient for requirements:

{
  "database": "demodata",
  "conn_string": "DSN=demodata",
  "host": "0.0.0.0",
  "port": 8000,
  "query_mode": "read-only",
  "write_confirmation": true
}

Full driver connection (with credentials)

Use this format when the database requires authentication. This bypasses the container's built-in odbc.ini and connects directly to the Zen engine.

{
  "database": "demodata",
  "conn_string": "Driver=/opt/actianzen/lib64/libodbcci.so;ServerName=host.docker.internal:1583;DBQ=DEMODATA;UID=myuser;PWD=mypassword",
  "host": "0.0.0.0",
  "port": 8000,
  "query_mode": "read-only",
  "write_confirmation": true
}

Configuration Reference¶

Required Fields

Field	Type	Description
`conn_string`	`string`	ODBC connection string. Use `DSN=<name>` for the built-in DSN, or a full driver string with `UID` and `PWD` for authenticated connections.
`host`	`string`	Bind address for the MCP server inside the container. Set this to `0.0.0.0` so the server is reachable from outside the container.
`port`	`integer`	Port the MCP server listens on. This must match the port exposed by Docker (default `8000`).

Optional Fields

Field	Type	Default	Description
`database`	`string`	—	Logical database name used for display purposes.
`max_rows`	`integer`	`1000`	Maximum number of rows returned per query response. Default is `1000`.
`log_level`	`string`	`INFO`	Server log verbosity. Valid values: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`.
`query_mode`	`string`	`read-only`	`read-only` or `read-write`. Determines which tools are registered. See Write support.
`write_confirmation`	`boolean`	`true`	Set to `false` to run the built-in write tools without the human approval prompt. The `mcp:write` scope check still applies. Applies only when `query_mode` is `read-write`.
`oauth`	`object`	—	OAuth configuration block for protected deployments, see Authentication for more information.
`extensions`	`array`	—	Extension modules to load, each an object with a required `module` and an optional `config`. For more information, see Extensions.

OAuth and user impersonation

Actian Zen does not support SET SESSION AUTHORIZATION. If you use OAuth, set user_impersonation: false in the oauth block. The server logs the authenticated user but does not enforce it at the database level.

Start the Server¶

Once the conf.json is ready, start the container and mount the configuration file:

docker run -d \
  --name zen-mcp \
  -p 8000:8000 \
  --add-host=host.docker.internal:host-gateway \
  -v $(pwd)/conf.json:/app/conf.json:ro \
  actian/zen-mcp-server:1.1.0

Container networking

-p 8000:8000 exposes the server port on the host. --add-host=host.docker.internal:host-gateway allows the container to reach services on the host machine (such as the Zen engine on port 1583). Docker Desktop on Windows and macOS resolves host.docker.internal automatically; Linux requires the --add-host flag.

Once the container is running, connect the MCP client to the exposed server endpoint using the host and port from the configuration.

Usage¶

After connecting, the MCP client automatically discovers the server's capabilities. You can then perform the following tasks:

Inspect before querying: List tables and review structure before writing SQL.
Run a query: Execute a read-only SQL statement and receive formatted results.
Explore relationships: Traverse foreign keys and related tables using ORM operations.

Next Steps¶

Write Support
Enable data-modifying SQL, and what gates each write.
Authentication
Secure the server with OAuth 2.0 and an external identity provider.
Tools Learn more about the SQL, ORM, and blob tools exposed by the Zen server.
Write support Enable query_mode, and see the scope and approval checks every write passes.
Resources Explore the resource types available through the server.
Prompts Use the built-in prompt templates for common workflows.
Extensions Add custom tools to the server with a Python extension.