DataZen Documentation
DataZen User Guide

DataZen API Tools

In addition to exposing pipelines as MCP Tools, DataZen can let an external agent operate the agent itself through the HTTP API. The open-source datazen-api-mcp package is a stdio MCP server that turns approved DZFunctionAppCore endpoints into MCP tools for both cloud and self-hosted deployments.

Use this when an agent needs to check health, list jobs, read history or logs, inspect variables and connection metadata, or start, stop, and activate pipelines — without building a custom API client.

Prefer a dedicated Service Token for MCP credentials. Some tools change agent state (dz_job_start, dz_job_stop, dz_job_active). Restrict the tool list in the MCP client when you only need read-only access.

What Is Exposed

The server is spec-driven: tool definitions live in a JSON specification loaded at startup. The current approved set focuses on operations that are safe and useful for agent workflows, including:

  • Agent health and status (dz_ping, dz_version, dz_status)
  • Job listing and summaries (dz_jobs, dz_jobs_summary, dz_job_info)
  • Execution status, history, logs, and output
  • Change-log listing for a job
  • Environment variables (list and get)
  • Connection metadata only (secrets are not returned)
  • Job start, stop, and activate/deactivate

Endpoints that return secrets, dashboard aggregates, or unsupported dynamic-job surfaces are intentionally excluded. See the npm package for the latest tool list.

Cloud vs Self-Hosted

Configure DZ_DEPLOYMENT as cloud (default) or selfhosted:

  • Cloud — routes include the agent id; set DZ_AGENT_ID and send credentials via Basic auth with a Service Token.
  • Self-hosted — the deployment is the agent; omit DZ_AGENT_ID and set DZ_DEPLOYMENT=selfhosted. Authentication is still required.

The same environment variables are shared with datazen-pipeline-mcp when DZ_FUNCTIONS_BASE_URL ends with /api, so one credential set can drive both servers. See MCP Settings for where to find each value.

Register the MCP Server

Register datazen-api-mcp in your MCP client with the same environment variables as datazen-pipeline-mcp. Cloud and self-hosted examples, credential locations, Service Token scopes, and URL rules are documented in MCP Settings.

For Hermes, register datazen-api in the mcp_servers block and keep secrets in $HERMES_HOME/.env with ${VAR} placeholders. To expose only read-only tools, use a tools.include whitelist in the Hermes config.

How This Differs from Pipeline MCP Tools

  • Pipeline MCP Tools run your SQL CDC pipelines and return their result sets (via Portal AI Chat or datazen-pipeline-mcp).
  • DataZen API Tools operate the agent control plane: status, jobs, history, variables, and lifecycle actions.

Many agentic setups use both: API tools to manage and observe pipelines, and pipeline tools to query governed data.

Related Topics