# Datris (pypi · datris-mcp-server)

The data control plane for AI agents — acquire, validate, land, and query data over MCP.

- Trust score: 79/100 (medium)
- Change this week: +3
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-09-21

## Components

- oci · `docker.io/datrisai/datris-mcp-server:1.34.1`: 7/100, [markdown](https://verifymcp.io/servers/datris-datris/docker-io-datrisai-datris-mcp-server-1-34-1.md), [page](https://verifymcp.io/servers/datris-datris/docker-io-datrisai-datris-mcp-server-1-34-1)
- pypi · `datris-mcp-server`: 79/100 (this document), [markdown](https://verifymcp.io/servers/datris-datris/datris-mcp-server.md), [page](https://verifymcp.io/servers/datris-datris/datris-mcp-server)

## Channel facts

- Registry: `pypi`
- Package: `datris-mcp-server`
- Version: `1.34.1`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-09-21.

- **Supply Chain Security**: 100/100
  - No malware found by supply-chain analysis.
  - No known CVEs affecting this package version or its production dependencies.
  - Runs hatchling.build at install time, a recognised native-build step with no shell scripting around it.
  - 0 of 32 dependencies flagged as unhealthy.
- **Provenance & Transparency**: 48/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (Apache-2.0).
  - Actively maintained (last published 0 days ago).
  - Publishes a security disclosure policy (SECURITY.md).
- **Schema Quality & AI Usability**: 77/100
  - 100% of prompts and resources have a non-trivial description (not blank, and not just the item's name).
  - AI-judged instruction clarity (excellent).
  - Context-footprint check failed: tool/resource definitions use about 20886 tokens (~271/item across 77 items; 75 tools + 2 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 63/100
  - Stability observed for 19 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Tool Safety**: 75/100
  - No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.
  - 0 of 7 tool(s) whose name or description implies an irreversible operation declare an MCP destructiveHint annotation; "delete_pipeline" implies "delete" and declares no destructiveHint at all, which the MCP spec reads as destructive by default.
  - An AI judge read all 77 captured unit(s) of tool text and found none that tries to manipulate the model reading it.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### How do I install the Datris MCP server?

Datris runs locally as a PyPI package, launched with uvx datris-mcp-server. Ready-made configuration for Claude, Cursor, VS Code, Codex and 5 more is on this page, copied from each client's own documentation.

### Claude

```bash
claude mcp add datris-datris -- uvx datris-mcp-server
```

### Cursor

```json
{
  "mcpServers": {
    "datris-datris": {
      "command": "uvx",
      "args": [
        "datris-mcp-server"
      ]
    }
  }
}
```

### VS Code

```json
{
  "servers": {
    "datris-datris": {
      "command": "uvx",
      "args": [
        "datris-mcp-server"
      ]
    }
  }
}
```

### Codex

```bash
codex mcp add datris-datris -- uvx datris-mcp-server
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "datris-datris": {
      "type": "local",
      "command": [
        "uvx",
        "datris-mcp-server"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add datris-datris --command uvx --arg datris-mcp-server
```

### Hermes

```yaml
mcp_servers:
  datris-datris:
    command: "uvx"
    args: ["datris-mcp-server"]
```

### Netclaw

```json
{
  "McpServers": {
    "datris-datris": {
      "Transport": "stdio",
      "Command": "uvx",
      "Arguments": [
        "datris-mcp-server"
      ]
    }
  }
}
```

### Vellum

```bash
assistant mcp add datris-datris -t stdio -c uvx -a datris-mcp-server
```

### Other

```json
{
  "mcpServers": {
    "datris-datris": {
      "command": "uvx",
      "args": [
        "datris-mcp-server"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-09-21 (score 79, +1)

- [functional] Package version: 1.34.0 → 1.34.1

### 2026-09-20 (score 78, 0)

- [security regression] Tool safety: pass → unverified
- [security regression] Stability: 0.57 → unverified
- [functional regression] Tool coverage: 100 → unverified
- [functional regression] Schema quality: 100 → unverified
- [functional regression] Capabilities: pass → unverified
- [functional] Package version: 1.33.1 → 1.34.0

### 2026-09-19 (score 78, +16)

- [security improvement] Malware scan: unverified → pass

### 2026-09-18 (score 62, −15)

- [security regression] Malware scan: pass → unverified
- [functional] Package version: 1.32.0 → 1.33.1
- [functional] Package version: 1.32.0 → 1.33.0

### 2026-09-17 (score 77, 0)

- [security regression] Stability: 0.47 → unverified
- [security regression] Tool safety: pass → unverified
- [functional regression] Tool coverage: 100 → unverified
- [functional regression] Schema quality: 100 → unverified
- [functional regression] Capabilities: pass → unverified
- [functional] Package version: 1.30.1 → 1.32.0

### 2026-09-16 (score 77, +1)

- [functional] Package version: 1.30.0 → 1.30.1

### 2026-09-14 (score 76, +1)

- [functional] Package version: 1.29.0 → 1.30.0

### 2026-09-12 (score 75, +1)

No change was recorded against any check on this day. Stability & Change Management went from 30 to 33. That category is still filling its 30-day observation window: 9 days of observed history at the previous scan, 10 at this one. The score rises as the window fills, whether or not the server changes.

## MCP tools (75)

### `list_pipelines` (~89 tokens)

List all registered pipeline configurations. Each pipeline defines a complete data processing flow: source format and schema, AI-powered data quality and transformations, and destination (database, message queue, or vector store). CALL THIS FIRST on any data-related user request — before suggesting external sources, before asking scope questions. The user almost always cares more about what's already in their Datris environment than about a generic options menu.

### `get_pipeline` (~45 tokens)

Get a specific pipeline configuration by name. Returns the full JSON config including source, dataQuality, transformation, preprocessor, and destination sections.

Input parameters:

- `pipeline` (string, required): Pipeline name

### `create_pipeline` (~2320 tokens)

Create a pipeline. FOUR destination categories: STRUCTURED (postgres, mongodb, snowflake, databricks) — send a TINY sample (via content_text) and the schema is auto-detected; snowflake additionally REQUIRES credentialsSecret (a Platform secret with account/user/privateKey or password — discover via list_platform_secrets), warehouse, and database; databricks additionally REQUIRES credentialsSecret (a Platform secret with host plus clientId/clientSecret or token), warehouse (the SQL warehouse ID), and database (the Unity Catalog name). OBJECTSTORE (objectstore — writes Parquet files, ORC files, or an Iceberg table to MinIO or AWS S3) — same shape as structured (CSV-only, sample required for schema detection), plus objectStore-specific knobs (bucket, prefix, fileFormat, partitionBy, writeMode; keyFields for iceberg+merge; provider+credentialsSecret for S3). VECTOR (pgvector, qdrant, weaviate, milvus, chroma) — no schema; pass ONLY pipeline + destination (and optionally filename for the file-extension hint), no sample at all. SCRATCH (scratch) — same sample-required shape as structured, nothing is landed; the run's rows come back on the status rollup (`resultPreview`) and via get_pipeline_result; results expire — use it when the user wants an answer now, a validation result, or a transformed view with no reason to keep the rows (see the KEEP-OR-SCRATCH RULE). SAMPLE-SIZE RULE: the sample exists ONLY for schema detection — send the header row plus 3-5 representative rows, NEVER a full dataset. Composing hundreds of rows here wastes minutes of generation time; the real data arrives later via the tap or upload_data. Prefer content_text (plain text) over content (base64) — the server encodes it for you. If this Datris instance's agent policy requires a person to approve this action, the call does NOT perform it: it returns status `pending_approval` with an `approvalId`. Tell the user it is waiting for approval in Datris, then poll `get_approval` with that id (pause with `w…

Input parameters:

- `authoritative` (boolean): OMIT BY DEFAULT. Pass false only when the user says this pipeline lands a derived copy (a rollup, a replica, an index built from another dataset) rather than the system of record. A pipeline's single…
- `bucket` (string): Object-store bucket name. Only applies to destination=objectstore. For MinIO this is optional (default: {environment}-data). For S3 (provider=s3) this is REQUIRED — there is no global default S3 buck…
- `catalog` (string): OMIT BY DEFAULT. Catalogs are a user-chosen organizational convention — do NOT set a catalog unless the user has explicitly asked to group this pipeline under a named catalog. Assigning one for them…
- `codegen_rule` (string): Optional data quality validation rule as a plain-English instruction. Only add when the user explicitly requests validation. Datris will generate a Python validation script from this instruction and…
- `codegen_transform` (string): Optional transformation instruction as a plain-English description. Only add when the user explicitly requests transformation. Datris will generate a Python script from this instruction and run it lo…
- `content` (string): Base64-encoded sample data. Prefer content_text instead — it's the same thing without you having to base64-encode. Only use this form when you already have base64 in hand (e.g. relaying an attachment…
- `content_text` (string): Plain-text sample data (the server base64-encodes it for you) — the preferred way to pass the sample for structured destinations (postgres, mongodb, snowflake, databricks) and objectstore. Header row…
- `credentialsSecret` (string): Name of an existing PLATFORM secret holding destination credentials. For objectstore + provider=s3: fields accessKey, secretKey, region (optionally sessionToken); REQUIRED unless Datris runs in AWS w…
- `database` (string): Destination database name (default: datris). Ignored for objectstore. REQUIRED for snowflake — there is no default Snowflake database; ask the user which one to load. REQUIRED for databricks — it nam…
- `deleteBeforeWrite` (boolean): When true, delete existing objects under the prefix before writing. Only applies to destination=objectstore. Default: false. Distinct from writeMode=overwrite (which is Spark-level).
- `delimiter` (string): CSV delimiter (default: comma)
- `destination` (string): Destination type (default: postgres for CSV, mongodb for JSON/XML). Use 'scratch' when nothing should be landed and the rows should come back to the caller (status rollup resultPreview + get_pipeline…
- `endpoint` (string): S3 endpoint URL override. Only applies to destination=objectstore + provider=s3. Must use https://. Leave unset for the AWS regional default. Ignored for provider=minio.
- `fileFormat` (string): Object-store storage format. Only applies to destination=objectstore. 'parquet' and 'orc' write loose columnar files under the prefix; 'iceberg' writes a table at the prefix (snapshots, schema evolut…
- `filename` (string): Filename (e.g., data.csv, report.json, orders.xml). REQUIRED for structured destinations and objectstore. Optional for vector destinations — only used as a fileExtension hint (defaults to txt).
- `header` (boolean): Whether CSV has a header row (default: true)
- `keyFields` (array): Optional natural-key columns used to dedupe / upsert rows on every run. Applies to postgres, mongodb, snowflake, and databricks destinations, and to objectstore when fileFormat=iceberg and writeMode=…
- `partitionBy` (array): Optional partition columns for objectstore writes. Spark creates a directory structure based on the distinct values of these columns. Field names must be in the destination schema. Example: ['dt', 'r…
- `pipeline` (string, required): Pipeline name
- `prefix` (string): Object-store key prefix under the bucket (e.g. 'sales/daily'). REQUIRED for destination=objectstore.
- `provider` (string): Object-store provider. Only applies to destination=objectstore. Default 'minio' (the platform's built-in store). Set to 's3' to write to AWS S3 — that requires bucket AND credentialsSecret.
- `reason` (string): Optional one-line reason for this change, recorded in the platform's audit log and shown to anyone asked to approve it.
- `role` (string): Optional Snowflake role to assume (e.g. DATRIS_LOADER). Only applies to destination=snowflake; omit to use the service user's default role.
- `schema` (string): Destination schema. Applies to destination=snowflake (default: PUBLIC) and destination=databricks (default: default). Simple identifiers resolve case-insensitively; names with hyphens/spaces are quot…
- `table` (string): Destination table or collection name (default: pipeline name). Ignored for objectstore (the destination is bucket+prefix, not a table).
- `truncate` (boolean): Optional. When true, the destination table/collection is truncated before each run, so only the latest run's data is kept. Only applies to postgres, mongodb, snowflake, and databricks destinations (o…
- `warehouse` (string): Compute that runs the load. For destination=snowflake: the virtual warehouse NAME (e.g. DATRIS_WH). For destination=databricks: the SQL warehouse ID from the warehouse's Connection details — the trai…
- `writeMode` (string): Object-store write mode. Only applies to destination=objectstore. Default: append. 'merge' is only valid with fileFormat=iceberg and requires keyFields — rows whose key matches an existing row replac…

### `set_catalog` (~298 tokens)

Set or clear the catalog grouping label on an existing pipeline or tap. ONLY call this when the user has explicitly asked to organize work under a named catalog. Do NOT call it proactively — catalogs are a user-chosen organizational convention; assigning one for them puts the pipeline/tap into a taxonomy they didn't ask for. Pass exactly one of `pipeline` or `tap` to identify the target. Pass `catalog` to set the label, or omit it (or pass an empty string) to clear it. Survives subsequent re-ingests — `datris ingest` no longer rewrites an existing pipeline's config. If this Datris instance's agent policy requires a person to approve this action, the call does NOT perform it: it returns status `pending_approval` with an `approvalId`. Tell the user it is waiting for approval in Datris, then poll `get_approval` with that id (pause with `wait_seconds` between polls) — do not re-issue the action.

Input parameters:

- `catalog` (string): Catalog label. Omit or pass an empty string to clear the label.
- `pipeline` (string): Pipeline name to update. Mutually exclusive with `tap`.
- `reason` (string): Optional one-line reason for this change, recorded in the platform's audit log and shown to anyone asked to approve it.
- `tap` (string): Tap name to update. Mutually exclusive with `pipeline`.

### `delete_pipeline` (~296 tokens)

Delete a pipeline. This is DESTRUCTIVE: by default it removes BOTH the pipeline configuration AND all data already written to the destination (MongoDB collection rows, Postgres table rows, vector-store entries). It also wipes document-tap ledgers and staged files for any tap that targets this pipeline, so a recreate gets a clean re-ingest. The platform deliberately does NOT support deleting just the config and orphaning the data — that creates ghost state. If you want to keep the config but wipe the destination data ("reset"), pass keep_config=true; the config survives, the data does not. ALWAYS confirm with the user before calling this tool. If this Datris instance's agent policy requires a person to approve this action, the call does NOT perform it: it returns status `pending_approval` with an `approvalId`. Tell the user it is waiting for approval in Datris, then poll `get_approval` with that id (pause with `wait_seconds` between polls) — do not re-issue the action.

Input parameters:

- `keep_config` (boolean): If true, delete only the destination data but keep the pipeline config (useful for a clean reset). Default false (full delete of both config and data).
- `pipeline` (string, required): Pipeline name to delete
- `reason` (string): Optional one-line reason for this change, recorded in the platform's audit log and shown to anyone asked to approve it.

### `upload_data` (~322 tokens)

Upload data to a registered pipeline for processing. Send the ENTIRE file content as a single base64-encoded string in ONE call — do not pre-split or chunk the content client-side. Vector destinations (pgvector, qdrant, weaviate, milvus, chroma) apply recursive chunking server-side using the pipeline's configured chunkSize/chunkOverlap; for those, one upload_data call yields many embedded chunks automatically. The pipeline's rules are applied: schema validation, data quality checks, transformations, then routing to the configured destination. A pipeline whose destination is scratch validates or transforms the file and hands the rows back (status rollup `resultPreview`, then get_pipeline_result) instead of landing them. Returns a pipelineToken for tracking job status via get_job_status. If this Datris instance's agent policy requires a person to approve this action, the call does NOT perform it: it returns status `pending_approval` with an `approvalId`. Tell the user it is waiting for approval in Datris, then poll `get_approval` with that id (pause with `wait_seconds` between polls) — do not re-issue the action.

Input parameters:

- `content` (string, required): Base64-encoded file content
- `filename` (string, required): Filename (e.g., data.csv, report.json, orders.xml)
- `pipeline` (string, required): Pipeline name to process the data with
- `reason` (string): Optional one-line reason for this change, recorded in the platform's audit log and shown to anyone asked to approve it.

### `get_job_status` (~307 tokens)

Get job status for an upload_data submission. Pass `pipeline_token` (returned from upload_data) for the recommended path. Pass `pipeline_name` instead for a paginated summary of recent jobs for that pipeline. When queried by `pipeline_token`, the response is `{rollup: {allDone, status, jobs: [...]}, events: [...]}` — poll every few seconds until `rollup.allDone` is true, then read `rollup.status` (`success` | `warning` | `error`) for the outcome. Per-job detail is in `rollup.jobs[]` with `pipelineToken`, `pipeline`, `filename`, `status`, `startedAt`, `lastEventAt`, `elapsed`, and `lastError` (populated on failure with `processName` and `description`). `events[]` is the raw begin/info/end audit trail; the rollup is the source of truth for completion. When queried by `pipeline_name`, the response is a paginated array of summary rows; the most recent job is index 0 and its `status` field is `success` | `processing` | `error`. Do NOT proceed to query/search until the job is in a terminal state.

Input parameters:

- `page` (integer): Page number for paginated results (default: 1)
- `pipeline_name` (string): Pipeline name to get a paginated summary of recent jobs
- `pipeline_token` (string): Pipeline token returned from upload_data

### `kill_job` (~155 tokens)

Kill a running pipeline job by its pipeline token. The job thread will be interrupted and the job marked as cancelled. If this Datris instance's agent policy requires a person to approve this action, the call does NOT perform it: it returns status `pending_approval` with an `approvalId`. Tell the user it is waiting for approval in Datris, then poll `get_approval` with that id (pause with `wait_seconds` between polls) — do not re-issue the action.

Input parameters:

- `pipeline_token` (string, required): Pipeline token of the running job to kill
- `reason` (string): Optional one-line reason for this change, recorded in the platform's audit log and shown to anyone asked to approve it.

### `profile_data` (~126 tokens)

Send data and use AI to generate a comprehensive data profile: summary statistics per column, data quality issues detected, and suggested validation rules. Use the suggested aiRule when building a pipeline's dataQuality section.

Input parameters:

- `content` (string, required): Base64-encoded file content
- `delimiter` (string): CSV delimiter (default: comma)
- `filename` (string, required): Filename (e.g., sample.csv)
- `header` (boolean): Whether CSV has a header row (default: true)
- `sample_size` (integer): Number of rows to sample for profiling (default: 200)

### `get_dest_types` (~152 tokens)

Propose real column types for a pipeline whose destination columns are all stored as text (the default for agent-created pipelines). Stateless: samples up to 1000 rows that already landed in the destination, infers types deterministically, and returns per-column evidence — a few sample values, plus (for columns kept as string by a dirty value) the offending value and the type it blocked. Only for postgres, snowflake, and databricks destinations; `eligible: false` with a `reason` of destination-not-supported, already-typed, or no-landed-rows (run the pipeline once first) otherwise. Nothing is stored or changed by this call.

Input parameters:

- `pipeline` (string, required): Pipeline name

### `apply_dest_types` (~292 tokens)

Apply destination column types to an all-string pipeline. REQUIRES explicit user approval first. Landed data is migrated before the config changes (postgres retypes in place; snowflake/databricks validate then swap the table) — the migration locks or replaces the table, so do NOT apply while a run is in flight. Any landed value that will not cast fails the whole apply with the column named and NOTHING changed — then either re-apply with that field set back to string, or fix the data. `fields` must list EVERY destination column (same names as get_dest_types returned) with its intended type; keep a column as-is by passing type string. If this Datris instance's agent policy requires a person to approve this action, the call does NOT perform it: it returns status `pending_approval` with an `approvalId`. Tell the user it is waiting for approval in Datris, then poll `get_approval` with that id (pause with `wait_seconds` between polls) — do not re-issue the action.

Input parameters:

- `fields` (array, required): Every destination column with its intended type. Types: string, boolean, int, bigint, float, double, date, timestamp.
- `pipeline` (string, required): Pipeline name
- `reason` (string): Optional one-line reason for this change, recorded in the platform's audit log and shown to anyone asked to approve it.

### `get_version` (~15 tokens)

Get the Datris server version.

### `check_service_health` (~79 tokens)

Check which backend services are up, down, or not configured. Returns the health status of PostgreSQL, MongoDB, MinIO, ActiveMQ, Kafka, and any configured vector databases (Qdrant, Weaviate, Milvus, Chroma, pgvector). Call this before attempting search or query operations to know which services are available.

### `run_doctor` (~211 tokens)

Run the platform's operational self-check and return a report: Vault token expiry, AI slot secrets complete, embedding model actually loaded, disk usage, the payload staging area (writable, room for one run, no orphaned run directories), component version skew, and (opt-in) whether each AI model answers. Each non-ok check carries a remediation command for the operator; nothing is changed. Do NOT call run_doctor as part of the normal workflow — it is slow. Only use it for diagnostics when something fails or the user asks about the deployment's health. Host-level checks (Docker volumes, container env drift) need `datris doctor` on the machine running Docker and are not included here.

Input parameters:

- `include_ai_probes` (boolean): Also send a minimal request through each configured AI slot to confirm the key and model work (spends a few tokens). Default false.
- `mode` (string): `full` (default) or `quick` (only the cheap startup-safe subset).

### `search_qdrant` (~103 tokens)

Semantic search across a Qdrant vector database collection. Takes a natural language query, generates an embedding, and returns the most similar document chunks with similarity scores. For RAG: pass the returned text to ai_answer with the user's question.

Input parameters:

- `collection` (string): Qdrant collection name (default: documents)
- `query` (string, required): Natural language search query
- `top_k` (integer): Number of results to return (default: 5)

### `search_weaviate` (~104 tokens)

Semantic search across a Weaviate vector database class. Takes a natural language query, generates an embedding, and returns the most similar document chunks with similarity scores. For RAG: pass the returned text to ai_answer with the user's question.

Input parameters:

- `class_name` (string): Weaviate class name (default: Documents)
- `query` (string, required): Natural language search query
- `top_k` (integer): Number of results to return (default: 5)

### `search_milvus` (~101 tokens)

Semantic search across a Milvus vector database collection. Takes a natural language query, generates an embedding, and returns the most similar document chunks with similarity scores. For RAG: pass the returned text to ai_answer with the user's question.

Input parameters:

- `collection` (string): Milvus collection name (default: documents)
- `query` (string, required): Natural language search query
- `top_k` (integer): Number of results to return (default: 5)

### `search_pgvector` (~127 tokens)

Semantic search across a PostgreSQL pgvector table using cosine distance. Takes a natural language query, generates an embedding, and returns the most similar document chunks with similarity scores. Use list_postgres_tables with vector_only=true to discover available pgvector tables. For RAG: pass the returned text to ai_answer.

Input parameters:

- `query` (string, required): Natural language search query
- `schema` (string): PostgreSQL schema (default: public)
- `table` (string): Table name (default: documents)
- `top_k` (integer): Number of results to return (default: 5)

### `search_chroma` (~100 tokens)

Semantic search across a Chroma vector database collection. Takes a natural language query, generates an embedding, and returns the most similar document chunks with similarity scores. For RAG: pass the returned text to ai_answer with the user's question.

Input parameters:

- `collection` (string): Chroma collection name (default: documents)
- `query` (string, required): Natural language search query
- `top_k` (integer): Number of results to return (default: 5)

### `query_postgres` (~236 tokens)

Execute a read-only SQL SELECT query against PostgreSQL. Use the metadata discovery tools (list_postgres_databases, list_postgres_schemas, list_postgres_tables, list_postgres_columns) first to explore available data before constructing queries. Only SELECT is allowed; LIMIT is auto-appended if missing. Queries are cancelled if they run too long, so avoid full-table scans. For approximate row counts — "how many rows / records does table X have", overviews, or summarizing several tables — do NOT run exact `SELECT COUNT(*)` (it scans the whole table and can take many seconds on a large one). Instead read the planner estimate, which is effectively instant regardless of table size: `SELECT reltuples::bigint AS estimate FROM pg_class WHERE relname = '<table>'`. Use exact `COUNT(*)` only when the user explicitly needs an exact count of a known-small or filtered result.

Input parameters:

- `limit` (integer): Maximum rows to return (default: 100). Pass -1 for unlimited — no cap, returns every matching row.
- `sql` (string, required): SQL SELECT query to execute

### `query_objectstore` (~237 tokens)

Read rows from a pipeline's objectStore destination (Parquet files, ORC files, or an Iceberg table in MinIO or AWS S3). Pass the pipeline name; the server resolves the bucket, prefix, format, and credentials from the pipeline config — same code path the writer uses, so MinIO and S3 destinations both work. Returns up to `limit` rows as JSON objects keyed by column name, plus the resolved s3a:// path and format for transparency. For an Iceberg table the response also carries snapshotId (a decimal string, not a number) and snapshotTimestamp (ISO-8601) of the snapshot read; both are null for other formats. Returns 0 rows (not an error) when the pipeline has no successful runs yet. This is the right tool when list_pipelines shows objectStore as the destination — query_postgres / query_mongodb / search_* will not work against objectStore data.

Input parameters:

- `limit` (integer): Maximum rows to return (default: 100, hard cap: 10000).
- `pipeline` (string, required): Pipeline name (from list_pipelines).

### `query_snowflake` (~301 tokens)

Run a read-only query against the Snowflake account a pipeline loads into. Pass the pipeline name; the server resolves the account, credentials, warehouse, and role from the pipeline's config — same connection the loader uses, credentials never leave the server. Only works for pipelines whose destination is Snowflake (database with useSnowflake=true). Allowed statements: SELECT (WITH/CTE), SHOW, and DESCRIBE — LIMIT is auto-appended to SELECTs. Omit `sql` to preview the pipeline's destination table (the 'did my load land?' check). Metadata discovery uses the same tool — there are no separate list_snowflake_* tools: `SHOW DATABASES`, `SHOW SCHEMAS IN DATABASE <db>`, `SHOW TABLES IN SCHEMA <db>.<schema>`, `DESCRIBE TABLE <db>.<schema>.<table>`, or query <db>.information_schema.columns. Queries run on the customer's configured warehouse (which costs them compute) — keep them targeted and let the default LIMIT stand unless the user asks for more.

Input parameters:

- `limit` (integer): Maximum rows to return (default: 100). Pass -1 for unlimited.
- `pipeline` (string, required): Pipeline name (from list_pipelines). Must have a Snowflake destination.
- `sql` (string): Read-only statement: SELECT/WITH, SHOW, or DESCRIBE. Omit to preview the pipeline's destination table.

### `query_databricks` (~322 tokens)

Run a read-only query against the Databricks workspace a pipeline loads into. Pass the pipeline name; the server resolves the workspace, credentials, SQL warehouse, and catalog from the pipeline's config — same connection the loader uses, credentials never leave the server. Only works for pipelines whose destination is Databricks (database with useDatabricks=true). Allowed statements: SELECT (WITH/CTE), SHOW, and DESCRIBE — LIMIT is auto-appended to SELECTs. Omit `sql` to preview the pipeline's destination table (the 'did my load land?' check). Metadata discovery uses the same tool — there are no separate list_databricks_* tools: `SHOW CATALOGS`, `SHOW SCHEMAS IN <catalog>`, `SHOW TABLES IN <catalog>.<schema>`, `DESCRIBE TABLE <catalog>.<schema>.<table>`, or query <catalog>.information_schema.columns. Queries run on the customer's SQL warehouse (which costs them compute) — keep them targeted and let the default LIMIT stand unless the user asks for more. If the warehouse is stopped, the first query auto-starts it and may take longer.

Input parameters:

- `limit` (integer): Maximum rows to return (default: 100). Pass -1 for unlimited.
- `pipeline` (string, required): Pipeline name (from list_pipelines). Must have a Databricks destination.
- `sql` (string): Read-only statement: SELECT/WITH, SHOW, or DESCRIBE. Omit to preview the pipeline's destination table.

### `query_mongodb` (~116 tokens)

Query a MongoDB collection with optional filter and projection. Use list_mongodb_databases and list_mongodb_collections first to discover available data. Returns matching documents as JSON.

Input parameters:

- `collection` (string, required): MongoDB collection name
- `filter` (object): MongoDB query filter (default: {})
- `limit` (integer): Maximum documents to return (default: 20). Pass -1 for unlimited — no cap, returns every matching document.
- `projection` (object): Fields to include/exclude (default: all fields)

### `query_natural` (~136 tokens)

Ask a question in natural language about data in a PostgreSQL table. The AI generates a SQL query from the question and table schema, executes it, and returns the results. Use this instead of writing SQL manually.

Input parameters:

- `database` (string): Database name (default: datris)
- `limit` (integer): Maximum rows to return (default: 100). Pass -1 for unlimited — no cap, returns every matching row.
- `question` (string, required): Natural language question about the data
- `schema` (string): PostgreSQL schema (default: public)
- `table` (string, required): PostgreSQL table name to query

### `list_postgres_databases` (~42 tokens)

List all PostgreSQL databases available in the Datris platform. Use this as the first step when exploring what data has been ingested into PostgreSQL destinations.

### `list_postgres_schemas` (~65 tokens)

List all schemas in a PostgreSQL database. Schemas organize tables within a database (e.g., 'public', 'analytics'). Use after list_postgres_databases to drill into a specific database.

Input parameters:

- `database` (string): Database name (default: datris)

### `list_postgres_tables` (~103 tokens)

List all tables in a PostgreSQL schema. Set vector_only=true to show only pgvector embedding tables, or false (default) to show regular data tables. Use after list_postgres_schemas.

Input parameters:

- `database` (string): Database name (default: datris)
- `schema` (string): Schema name (default: public)
- `vector_only` (boolean): If true, only return tables with an embedding column (pgvector tables). Default: false

### `list_postgres_columns` (~75 tokens)

List all columns and their data types for a specific PostgreSQL table. Use this to understand table structure before writing a query_postgres SQL query.

Input parameters:

- `database` (string): Database name (default: datris)
- `schema` (string): Schema name (default: public)
- `table` (string, required): Table name

### `list_mongodb_databases` (~42 tokens)

List all MongoDB databases available in the Datris platform. Use this as the first step when exploring what data has been ingested into MongoDB destinations.

### `list_mongodb_collections` (~61 tokens)

List MongoDB collections. If database is specified, lists collections in that database. If omitted, lists all collections across all databases in 'db.collection' format.

Input parameters:

- `database` (string): Database name (optional; omit to list from all databases)

### `list_qdrant_collections` (~36 tokens)

List all collections in the Qdrant vector database. Use this to discover available collections before running search_qdrant.

### `list_weaviate_classes` (~35 tokens)

List all classes in the Weaviate vector database. Use this to discover available classes before running search_weaviate.

### `list_milvus_collections` (~35 tokens)

List all collections in the Milvus vector database. Use this to discover available collections before running search_milvus.

### `list_chroma_collections` (~33 tokens)

List all collections in the Chroma vector database. Use this to discover available collections before running search_chroma.

### `list_pgvector_collections` (~39 tokens)

List all pgvector tables (tables with an embedding column) in PostgreSQL. Use this to discover available collections before running search_pgvector.

### `ai_answer` (~143 tokens)

Ask the Datris AI to answer a question based on provided context. Ideal for RAG workflows: first retrieve relevant chunks using a search tool (search_qdrant, search_pgvector, etc.), then pass the retrieved text as context along with the user's question to get a synthesized answer.

Input parameters:

- `context` (string, required): Context text to base the answer on (e.g., retrieved document chunks)
- `query` (string, required): The question to answer
- `sources` (array): Optional provenance handles for the context (e.g. find_data results or _datris_* fields from search hits). Echoed back unchanged on the response so the answer and its provenance travel together.

### `upload_config` (~199 tokens)

Upload a configuration file to the Datris platform. Supports 'validation-schema' (JSON Schema files used in pipeline dataQuality schema validation). Send the file content as base64. If this Datris instance's agent policy requires a person to approve this action, the call does NOT perform it: it returns status `pending_approval` with an `approvalId`. Tell the user it is waiting for approval in Datris, then poll `get_approval` with that id (pause with `wait_seconds` between polls) — do not re-issue the action.

Input parameters:

- `content` (string, required): Base64-encoded file content
- `filename` (string, required): Filename (e.g., schema.json, transform.js)
- `reason` (string): Optional one-line reason for this change, recorded in the platform's audit log and shown to anyone asked to approve it.
- `type` (string, required): Config file type: 'validation-schema' for JSON Schema

### `update_secret` (~236 tokens)

Update an AI provider secret in the Datris platform. Use this to configure your AI API keys so Datris can use AI features (data profiling, schema generation, AI transformations, RAG). Only AI-related secrets can be updated: anthropic, openai, azure, grok, ollama, embedding. If this Datris instance's agent policy requires a person to approve this action, the call does NOT perform it: it returns status `pending_approval` with an `approvalId`. Tell the user it is waiting for approval in Datris, then poll `get_approval` with that id (pause with `wait_seconds` between polls) — do not re-issue the action.

Input parameters:

- `fields` (object, required): Key-value fields to set. Typical fields: endpoint (API URL), model (model name), apiKey (API key)
- `name` (string, required): Secret name: anthropic, openai, azure, grok, ollama, or embedding
- `reason` (string): Optional one-line reason for this change, recorded in the platform's audit log and shown to anyone asked to approve it.

### `list_tap_secrets` (~92 tokens)

List the names of tap secrets that already exist (secrets tagged _type=tap — both agent-created and human-owned ones surfaced via the UI's Tap Secrets section). ALWAYS call this before create_tap_secret: if a suitable secret already exists, prefer reusing it by passing its name as secret_name to create_tap. Only ask the user to provide credentials when no existing secret covers the need.

### `get_tap_secret_fields` (~91 tokens)

Return the FIELD NAMES (keys only — never values) of an existing tap secret. Use this after list_tap_secrets to verify a candidate secret has the keys your tap script will need (e.g. API_KEY, USER_AGENT). Secret values are intentionally NOT returned and are never visible to the agent.

Input parameters:

- `name` (string, required): Tap secret name (from list_tap_secrets).

### `list_platform_secrets` (~149 tokens)

List the names of PLATFORM secrets (all secrets NOT tagged _type=tap — the Platform tab in the UI's Secrets section). These are human-owned credentials for destinations and infrastructure (e.g. S3 destination credentials, Postgres connection, MongoDB connection, embedding/vector-store endpoints). The agent can READ these (to look up their names and field shape via get_platform_secret_fields and reference them in pipeline configs) but cannot create, update, or delete them — those operations are the user's responsibility via the Secrets tab. Use this whenever a pipeline's destination needs a credentialsSecret reference (e.g. objectStore with provider=s3) and you need to discover which secrets the user already has.

### `get_platform_secret_fields` (~111 tokens)

Return the FIELD NAMES (keys only — never values) of an existing platform secret. Use this after list_platform_secrets to verify a candidate secret has the keys a destination config requires (e.g. an S3 credentialsSecret must contain accessKey, secretKey, region). Secret values are intentionally NOT returned. If the named secret is tap-tagged, this tool refuses — use get_tap_secret_fields for those.

Input parameters:

- `name` (string, required): Platform secret name (from list_platform_secrets).

### `create_tap_secret` (~388 tokens)

Create or update a secret for a tap to use. The secret's fields are injected as environment variables into the tap's Python script at runtime. Use this before create_tap when the tap needs credentials (API key, DB password, etc.). FIRST call list_tap_secrets to check whether a suitable secret already exists — if so, reuse it instead of creating a duplicate. By default, fails if a secret with this name already exists — pass overwrite=true to replace it (ask the user first). Agents can only overwrite secrets that were also created by an agent (tagged _type=tap); secrets owned by a human user must be updated via the UI. If this Datris instance's agent policy requires a person to approve this action, the call does NOT perform it: it returns status `pending_approval` with an `approvalId`. Tell the user it is waiting for approval in Datris, then poll `get_approval` with that id (pause with `wait_seconds` between polls) — do not re-issue the action.

Input parameters:

- `fields` (object, required): Key-value fields. Each key becomes an env var name in the tap script; e.g., {"apiKey": "sk_..."} is read as os.environ['apiKey'].
- `name` (string, required): Secret name. Must not use reserved AI-slot names (anthropic, openai, azure, grok, ollama, embedding, ai-primary, codegen). Convention: lowercase, hyphenated, e.g. 'stripe-api-key'.
- `overwrite` (boolean): If true, replace an existing secret with the same name. Default false (fails on collision). Only tap-typed secrets can be overwritten by an agent.
- `reason` (string): Optional one-line reason for this change, recorded in the platform's audit log and shown to anyone asked to approve it.

### `delete_tap_secret` (~185 tokens)

Delete a tap secret. Only secrets created by an agent (tagged _type=tap) can be deleted via this tool; secrets owned by a human user must be removed from the Secrets tab. Use this to clean up after a tap is no longer needed. If this Datris instance's agent policy requires a person to approve this action, the call does NOT perform it: it returns status `pending_approval` with an `approvalId`. Tell the user it is waiting for approval in Datris, then poll `get_approval` with that id (pause with `wait_seconds` between polls) — do not re-issue the action.

Input parameters:

- `name` (string, required): Name of the tap secret to delete.
- `reason` (string): Optional one-line reason for this change, recorded in the platform's audit log and shown to anyone asked to approve it.

### `create_tap` (~1546 tokens)

Create a tap — a fetcher that pulls data from an external source and pushes it into a pipeline. Two kinds: a Python script the platform executes (default — provide a plain-English `instruction` to have AI generate the script, or supply your own `script` directly), or `kind: "http"` — a user-hosted HTTP endpoint (any language) that Datris POSTs the run context to on each run and which responds with the tap envelope; pass `endpoint_url` and see the tap-http-contract doc. HTTP taps run no code on the platform; AI script generation and the DATRIS_PLATFORM_* platform-data callback do NOT apply to them, so keep any tap whose fetch logic reads platform data as a Python tap. If the user wants the tap to feed a pipeline, pass `target_pipeline` now. Without it, `run_tap` will fetch but not persist (response will show `persisted: false, persistedReason: "no_target_pipeline"`) — you'd then need to call update_tap to wire a pipeline. For a fetch-only tap (the user wants the rows back, not landed), target a pipeline whose destination is scratch — see the KEEP-OR-SCRATCH RULE in the server instructions. If the user mentioned ANY recurrence (nightly, daily, hourly, every morning, market open, etc.), pass `cron_expression` NOW — the platform's scheduler will run the tap on that cadence automatically. This is the canonical way to make a tap recurring; do NOT respond with shell commands or external schedulers for the user to run themselves. See the SCHEDULING RULE in the server instructions. AFTER creating, call `test_tap` to validate the script BEFORE any `run_tap` or before relying on a scheduled cron run — see the VALIDATION RULE. Setting a cron on a never-tested script is a guaranteed-bad nightly run waiting to happen. The platform enforces this: passing `cron_expression` for a script (or endpoint) that has not passed `test_tap` returns HTTP 409 with the remedy — create the tap without `cron_expression`, call `test_tap` until it succeeds, then `update_tap` with the cron. Replacin…

Input parameters:

- `cron_expression` (string): Quartz CRON expression for recurring runs (e.g., '0 0 * * * ?' for hourly, '0 30 5 ? * MON-FRI' for weekdays 5:30am). SET THIS whenever the user describes a recurrence — nightly, daily, hourly, marke…
- `endpoint_url` (string): For kind 'http' only: absolute http(s) URL Datris POSTs {tap, params, state, testLimit} to on each run. The endpoint responds with the tap envelope {type, data, state?, logs?}. If the tap's secret ha…
- `instruction` (string): Plain-English instruction for AI script generation. Describe the source and the data to fetch, in one or two sentences. If provided, AI generates the Python script.
- `kind` (string): Tap implementation kind. 'python' (default): a script the platform executes. 'http': a user-hosted endpoint speaking the tap HTTP contract — requires `endpoint_url`; `instruction`, `script`, and `pac…
- `name` (string, required): Unique tap name.
- `packages` (array): Extra pip packages the script imports that aren't pre-installed. Required when `script` imports non-stdlib modules beyond the pre-installed set (requests, beautifulsoup4, pandas, lxml, feedparser, bo…
- `reason` (string): Optional one-line reason for this change, recorded in the platform's audit log and shown to anyone asked to approve it.
- `script` (string): Raw Python source code with a fetch() function. Use this to provide your own script instead of AI generation.
- `secret_name` (string): Vault secret name containing API keys/credentials the script needs for the EXTERNAL source. Never for the platform's own databases — scripts reach platform data credential-free via the auto-injected…
- `source` (string): Where the data really comes from, as a short provider name or host, for lineage and provenance. Optional: when omitted it is derived from the endpoint host or the host the script references most. Nev…
- `tap_type` (string): Tap type. 'structured' (default) returns rows of records. 'document' returns a list of {uri, filename, content (base64)} dicts; the platform stages each document and uses a ledger to skip files it ha…
- `target_pipeline` (string): Name of the pipeline to push fetched data into

### `list_taps` (~73 tokens)

List all taps with their status, target pipeline, schedule, and last run info. CALL THIS FIRST (alongside list_pipelines) on any data-related user request — the user's existing taps often reveal what's already being pulled and where, which short-circuits the entire 'should I suggest an external API?' conversation.

### `run_tap` (~1226 tokens)

Manually trigger a tap. Executes the script; when a target pipeline is configured, hands records to the pipeline async. The response carries `recordCount`, `publisherToken`, `pipelineTokens`, `persisted`, `persistedReason`, and the script's `logs` — but NOT the records themselves. If you need to preview what the script produces, call `test_tap` instead. BEFORE the first run of a newly-created or newly-updated tap, you MUST have called `test_tap` and seen it succeed. See the VALIDATION RULE in the server instructions. Skipping the test on a fresh script pushes potentially-broken data into the destination — and `run_tap` doesn't return records, so you won't see the breakage from the response. 

PER-RUN PARAMS — pass a `params` object to drive this run with caller-supplied values (date range, id list, page cursor, etc.). Each key/value becomes an env var the script reads via `os.environ.get('DATRIS_TAP_PARAM_<key>')`. Keys must match `[A-Za-z_][A-Za-z0-9_]*` so they map cleanly onto env var names. Values are stringified; nested objects/arrays are JSON-encoded (script can `json.loads()` them back). Use this for anything that varies per-call — date windows, id lists, page cursors, batch sizes. Do NOT rewrite the tap secret to pass per-run params: secrets are for credentials (API keys, DB passwords); rewriting them on every call clobbers concurrent runs, pollutes audit history, and wastes Vault writes. If the tap script doesn't yet read a particular param, update the script by calling `create_tap` again with the same `name` and a revised `script` (create_tap upserts and replaces the existing script). That's the right shape for parameterized runs.

REQUIRED next steps based on the response:
  • `persisted: true` → load is still running. Call `get_pipeline_status(publisher_token=response.publisherToken)` and poll until `rollup.allDone` is true. Then read `rollup.status` (`success`/`warning`/`error`) and `rollup.jobs[].lastError`. Do not report completion or query the desti…

Input parameters:

- `name` (string, required): Name of the tap to run
- `params` (object): Optional per-run parameters injected into the script as DATRIS_TAP_PARAM_<key> env vars. Use for values that vary per call (date ranges, id lists, page cursors, batch sizes) — NOT for credentials (th…
- `reason` (string): Optional one-line reason for this change, recorded in the platform's audit log and shown to anyone asked to approve it.

### `get_pipeline_status` (~270 tokens)

Read pipeline ingestion status. Use this after `run_tap` to watch a tap-submitted load progress. Pass `publisher_token` to see every job the tap run submitted (the recommended option — works for both structured and document taps). Pass `pipeline_token` for a single ingestion job. Exactly one of the two must be supplied. Response shape: `{rollup: {allDone, status, jobs: [...]}, events: [...]}`. Poll every few seconds until `rollup.allDone` is true, then read `rollup.status` (`success` | `warning` | `error`) for the outcome. Per-job detail is in `rollup.jobs[]` — each entry has `pipelineToken`, `pipeline`, `filename`, `status`, `startedAt`, `lastEventAt`, `elapsed`, and `lastError` (populated on failure with `processName` and `description`). `events[]` is the raw begin/info/end audit trail if you need it; the rollup is the source of truth for completion.

Input parameters:

- `pipeline_token` (string): UUID for a single ingestion job. Returns status rows for that one job.
- `publisher_token` (string): UUID returned from run_tap response. Returns status rows for ALL jobs this tap run submitted.

### `get_pipeline_result` (~401 tokens)

Read the rows a scratch pipeline produced. Only pipelines whose destination is scratch have a result — anything else is a 404 (an error body of `Not Found` / `status: 404` — rather than the endpoint's own `Only scratch pipelines have a result` message — for a pipeline you know is scratch means the server predates scratch results: report the version mismatch and stop, do not retry). The first rows are already on the `get_pipeline_status` rollup as `resultPreview`, so call this ONLY when the rollup's `resultTruncated` is true and you need the rest. Paging with `offset`/`limit` never re-runs the source — it reads the stored result. `limit` is clamped server-side, so the next offset is always `offset + returnedCount`, never `offset + limit`. Results expire after the retention window, so read them promptly; a 410 means the result is gone and the pipeline must be run again. Pass `publisher_token` (from run_tap) or `pipeline_token` (a single ingestion job); exactly one of the two must be supplied. Response shape: `{records: [...], rowCount, returnedCount, offset, truncated, resultUri, resultExpiresAt}` — `rowCount` is the whole result, `returnedCount` this page.

Input parameters:

- `limit` (integer): Requested rows for this page. The server clamps it to its inline cap; read returnedCount for what actually came back.
- `offset` (integer): Row offset to start from (default 0). Use the previous page's offset + returnedCount (not + limit — limit is clamped server-side).
- `pipeline_token` (string): UUID of a single ingestion job (from upload_data or rollup.jobs[].pipelineToken).
- `publisher_token` (string): UUID returned from run_tap. Reads the result of the scratch pipeline job that run submitted.

### `delete_tap` (~138 tokens)

Delete a tap and its stored script. If this Datris instance's agent policy requires a person to approve this action, the call does NOT perform it: it returns status `pending_approval` with an `approvalId`. Tell the user it is waiting for approval in Datris, then poll `get_approval` with that id (pause with `wait_seconds` between polls) — do not re-issue the action.

Input parameters:

- `name` (string, required): Name of the tap to delete
- `reason` (string): Optional one-line reason for this change, recorded in the platform's audit log and shown to anyone asked to approve it.

### `get_tap` (~148 tokens)

Get a tap's static definition: configuration, schedule, target pipeline, and the generated Python script content. This is config-only — it returns the SAME data on every call and tells you NOTHING about run state. Do NOT call this to check whether a run is finished or to poll for completion — repeatedly calling get_tap after run_tap is a bug, the response will never change to reflect ingestion progress. For run status: call `get_pipeline_status(publisher_token=...)` (token comes from the run_tap response or from a get_tap_logs entry). For run history: call `get_tap_logs`.

Input parameters:

- `name` (string, required): Name of the tap to retrieve

### `get_tap_logs` (~216 tokens)

Get the run history for a tap. Returns the last 50 run log entries sorted by most recent first, including status, record count, duration, errors, logs, and `publisherToken` for each run that submitted records to a pipeline. Works for both manual runs (triggered by `run_tap`) and scheduled runs (triggered by the platform's cron scheduler) — they share the same log. Use this to verify whether a scheduled run fired, whether any recent run's script succeeded, and to recover the `publisherToken` for any run if you didn't keep the original `run_tap` response in context. To verify the actual destination ingestion outcome — not just that the script ran — pick the relevant entry and call `get_pipeline_status(publisher_token=entry.publisherToken)`. The tap log only records what the script did; the publisher token is how you trace a run through to whether the data actually landed in the destination.

Input parameters:

- `name` (string, required): Name of the tap to get logs for

### `get_tap_ledger` (~176 tokens)

For a document tap: return the ledger of discovered documents (URI, filename, status, hashes, first/last seen timestamps). The ledger is what tells the platform which documents have already been processed so re-runs skip unchanged files. Pass 'clear_uri' to delete one entry (forces that document to be re-processed on the next run) or 'clear_all=true' to wipe the entire ledger (forces a full re-scan).

Input parameters:

- `clear_all` (boolean): Optional. If true, deletes the entire ledger for this tap, forcing every document to be re-processed on the next run.
- `clear_uri` (string): Optional. If set, deletes the ledger entry for this URI so the document is re-processed on the next run.
- `name` (string, required): Name of the document tap

### `get_tap_state` (~125 tokens)

Get a tap's incremental-sync state — the bookmark/cursor its script saved after the last successful run (injected into the next run as the DATRIS_TAP_STATE env var). Returns `{tap, state, updatedAt, updatedBy}`; `state` is null when the tap has never committed state (non-incremental tap, or no successful run yet). Use this to see where an incremental tap will resume from, or to debug why a scheduled tap is re-fetching or skipping a window.

Input parameters:

- `name` (string, required): Name of the tap

### `set_tap_state` (~324 tokens)

Overwrite or reset a tap's incremental-sync state. Pass `state` (a JSON object) to set the bookmark the next run receives via DATRIS_TAP_STATE — e.g. rewind a cursor so a window is re-fetched. Pass `reset: true` to delete the state entirely: the next run sees no DATRIS_TAP_STATE and does a full first-run fetch. The state shape is defined by the tap's own script (read its code via get_tap to see what keys it expects). Only use this on explicit request or to recover a broken cursor — normal runs manage state themselves, committing it only after a successful run. If this Datris instance's agent policy requires a person to approve this action, the call does NOT perform it: it returns status `pending_approval` with an `approvalId`. Tell the user it is waiting for approval in Datris, then poll `get_approval` with that id (pause with `wait_seconds` between polls) — do not re-issue the action.

Input parameters:

- `name` (string, required): Name of the tap
- `reason` (string): Optional one-line reason for this change, recorded in the platform's audit log and shown to anyone asked to approve it.
- `reset` (boolean): If true, delete the stored state entirely (next run = full first-run fetch). Ignores `state`.
- `state` (object): The state object the next run should receive. Must match the keys the tap's script reads from DATRIS_TAP_STATE.

### `test_tap` (~270 tokens)

Test-run a tap without pushing data to the pipeline. Executes the tap's script and returns results, record count, and any errors. Use this to validate a script before running it for real. If the error reports exit code -9 (or 137, or "killed") with no traceback, the script ran out of memory because fetch() built its whole result in memory: rewrite fetch() to yield records one at a time (read the source in chunks / pages) instead of returning a list, then test again. After two consecutive failed tests, stop and report the exact error text to the user instead of iterating further; never probe the runner environment or read the wrapper to diagnose. If this Datris instance's agent policy requires a person to approve this action, the call does NOT perform it: it returns status `pending_approval` with an `approvalId`. Tell the user it is waiting for approval in Datris, then poll `get_approval` with that id (pause with `wait_seconds` between polls) — do not re-issue the action.

Input parameters:

- `name` (string, required): Name of the tap to test
- `reason` (string): Optional one-line reason for this change, recorded in the platform's audit log and shown to anyone asked to approve it.

### `update_tap` (~583 tokens)

Update an existing tap's CONFIG without regenerating the script. Change the enabled state, CRON schedule, target pipeline, or description. USE THIS to set or adjust a tap's schedule (`cron_expression`) whenever the user describes a recurrence (nightly, daily, every morning, market open, etc.). The platform's scheduler runs the tap on the cadence you set — no external cron, Airflow DAG, or shell loop is needed (or wanted). See the SCHEDULING RULE in the server instructions. VALIDATION RULE: if you're enabling a `cron_expression` on a tap whose script has NEVER been validated, call `test_tap` FIRST and confirm it succeeds. The cadence-change path is safe for taps that have already run successfully; it is not safe to set a cron on a never-tested script. The platform enforces this: setting `cron_expression` on an untested script returns HTTP 409 with the remedy — save the tap without the cron, call `test_tap` until it succeeds, then call `update_tap` again with the cron. Cadence-only changes on a tap whose current script has passed `test_tap` are accepted. To change the SCRIPT itself, call `create_tap` again with the same `name` and the new `script` or `instruction` — create_tap upserts by name and replaces the existing script. There is no separate script-only update tool. If this Datris instance's agent policy requires a person to approve this action, the call does NOT perform it: it returns status `pending_approval` with an `approvalId`. Tell the user it is waiting for approval in Datris, then poll `get_approval` with that id (pause with `wait_seconds` between polls) — do not re-issue the action.

Input parameters:

- `cron_expression` (string): Quartz CRON expression for recurring runs (e.g., '0 0 * * * ?' for hourly, '0 30 5 ? * MON-FRI' for weekdays 5:30am). SET THIS whenever the user describes a recurrence — nightly, daily, hourly, marke…
- `description` (string): New plain-English description
- `enabled` (boolean): Enable or disable the tap
- `endpoint_url` (string): For HTTP taps only: new endpoint URL Datris POSTs the run context to. Rejected on Python taps.
- `name` (string, required): Name of the tap to update
- `reason` (string): Optional one-line reason for this change, recorded in the platform's audit log and shown to anyone asked to approve it.
- `target_pipeline` (string): New target pipeline name

### `list_tap_versions` (~199 tokens)

List the change HISTORY of a tap's definition, newest first. Each entry has `version`, `createdAt`, `createdBy`, and `changeNote`. The platform snapshots a tap's config + script every time it is created or updated. Read-only. IMPORTANT: an EMPTY result does NOT mean the tap has no version — it means the tap has not been edited since versioning was enabled, so no change snapshots exist yet. The tap's CURRENT version number is the `version` field on the tap itself (from `list_taps` or `get_tap`), which is at least 1 for every tap. Use this tool for 'what changed and when'; use `list_taps`/`get_tap` for 'what version is it on now'. See also `get_tap_version`, `diff_tap_versions`, `restore_tap_version`.

Input parameters:

- `name` (string, required): Name of the tap

### `get_tap_version` (~77 tokens)

View one historical snapshot of a tap's definition: the full config and the pinned Python script as they were at that version. Read-only; does not change the live tap. Get version numbers from `list_tap_versions`.

Input parameters:

- `name` (string, required): Name of the tap
- `version` (integer, required): Version number to view

### `diff_tap_versions` (~95 tokens)

Compare two versions of a tap's definition. Returns a server-computed field-by-field config diff and a line-level diff of the script. Read-only. `version` is the newer/selected snapshot; `against` is the baseline to compare it to.

Input parameters:

- `against` (integer, required): Baseline version to compare against
- `name` (string, required): Name of the tap
- `version` (integer, required): Selected version

### `restore_tap_version` (~273 tokens)

Roll a tap back (or forward) to a prior definition version. This is APPEND-ONLY and SIDE-EFFECTING: it reads snapshot `version` and writes it as a NEW latest version (config + that version's script), preserving the full history — nothing is overwritten or lost. 'Rolling forward' is the same call with a higher version number. Only call this when the operator has explicitly asked to restore/roll back this specific tap to a specific version. It does NOT run the tap — after restoring, report the new version and stop; do not chain into `run_tap` unless separately and explicitly asked. If this Datris instance's agent policy requires a person to approve this action, the call does NOT perform it: it returns status `pending_approval` with an `approvalId`. Tell the user it is waiting for approval in Datris, then poll `get_approval` with that id (pause with `wait_seconds` between polls) — do not re-issue the action.

Input parameters:

- `name` (string, required): Name of the tap
- `reason` (string): Optional one-line reason for this change, recorded in the platform's audit log and shown to anyone asked to approve it.
- `version` (integer, required): Version to restore (becomes a new latest version)

### `list_pipeline_versions` (~180 tokens)

List the change HISTORY of a pipeline's definition, newest first. Each entry has `version`, `createdAt`, `createdBy`, and `changeNote`. The platform snapshots a pipeline's full config every time it is created or updated. Read-only. IMPORTANT: an EMPTY result does NOT mean the pipeline has no version — it means it has not been edited since versioning was enabled. The CURRENT version number is the `version` field on the pipeline itself (from `list_pipelines` or `get_pipeline`), at least 1 for every pipeline. Use this tool for 'what changed and when'; use `list_pipelines`/`get_pipeline` for 'what version is it on now'. See also `get_pipeline_version`, `diff_pipeline_versions`, `restore_pipeline_version`.

Input parameters:

- `name` (string, required): Name of the pipeline

### `get_pipeline_version` (~70 tokens)

View one historical snapshot of a pipeline's definition: the full config as it was at that version. Read-only; does not change the live pipeline. Get version numbers from `list_pipeline_versions`.

Input parameters:

- `name` (string, required): Name of the pipeline
- `version` (integer, required): Version number to view

### `diff_pipeline_versions` (~82 tokens)

Compare two versions of a pipeline's definition. Returns a server-computed field-by-field config diff. Read-only. `version` is the newer/selected snapshot; `against` is the baseline.

Input parameters:

- `against` (integer, required): Baseline version to compare against
- `name` (string, required): Name of the pipeline
- `version` (integer, required): Selected version

### `restore_pipeline_version` (~230 tokens)

Roll a pipeline back (or forward) to a prior definition version. APPEND-ONLY and SIDE-EFFECTING: reads snapshot `version` and writes it as a NEW latest version, preserving full history. 'Rolling forward' is the same call with a higher version number. Only call this when the operator has explicitly asked to restore/roll back this specific pipeline to a specific version. Report the new version and stop. If this Datris instance's agent policy requires a person to approve this action, the call does NOT perform it: it returns status `pending_approval` with an `approvalId`. Tell the user it is waiting for approval in Datris, then poll `get_approval` with that id (pause with `wait_seconds` between polls) — do not re-issue the action.

Input parameters:

- `name` (string, required): Name of the pipeline
- `reason` (string): Optional one-line reason for this change, recorded in the platform's audit log and shown to anyone asked to approve it.
- `version` (integer, required): Version to restore (becomes a new latest version)

### `wait_seconds` (~262 tokens)

Sleep for a fixed number of seconds, then return. Use this to pace polling against long-running platform work (most often `get_pipeline_status` after `run_tap`, or `get_job_status` after `upload_data`) so you do not burn tool calls hammering an endpoint that is still in progress. ALWAYS poll once BEFORE the first wait — many runs finish in 1–5 seconds. Then use exponential backoff between polls: 5s, 10s, 20s, 30s, 60s, 60s, ... (cap at 60s normally, 120s only if the run is genuinely glacial). Reset to a short wait (5–15s) on the next cycle whenever a poll shows new jobs flipped to a terminal state — that means you're close to done. If 80%+ of jobs are terminal, wait ~15s; if only 1–2 jobs remain, wait ~10s. Hard upper bound is 120 seconds per call — for longer waits, call this tool in a loop interleaved with a status check.

Input parameters:

- `seconds` (integer, required): How long to sleep, in seconds. Range: 1–120. Values outside this range are clamped.

### `get_agent_policy` (~128 tokens)

Read this Datris instance's agent policy: for each action (e.g. tap:delete, pipeline:update:dest-types) whether an agent may do it on its own (auto), must wait for a person to approve it (approve), or is refused (deny). Call this before a delete, schema migration, or other consequential change to know whether it will run immediately or queue for approval, and tell the user accordingly. Returns {enabled, policy:{actions, overrides, limits}, actions:[all policy-able action keys], pendingCount}. When enabled is false, every action is auto.

### `list_pending_approvals` (~120 tokens)

List the actions this agent queued for human approval under the agent policy, newest first. Each entry has id, action, resource, state (pending | approved | rejected | expired | executed | failed), createdAt, expiresAt and — once decided — decidedBy and the result. Use `state` to filter (default: all).

Input parameters:

- `limit` (integer): Maximum entries to return (default 100).
- `state` (string): Filter by state: pending, approved, rejected, expired, executed, failed. Omit for all.

### `get_approval` (~143 tokens)

Poll one queued approval by the `approvalId` a mutating tool returned with status pending_approval. Returns its current state: pending (still waiting for a person), executed (approved and performed — `resultStatus` / `resultBody` carry the outcome of the original call), failed (approved but the replay failed), rejected, or expired. Poll with `wait_seconds` between calls, backing off to 30-60s; a decision can take minutes or hours, so after a few polls tell the user you will check back and stop polling unless they ask you to wait.

Input parameters:

- `approval_id` (string, required): The approvalId returned with pending_approval.

### `list_incidents` (~176 tokens)

List the platform's recovery-agent incidents, newest first. An incident is opened by the platform itself when a scheduled tap finally fails, a pipeline job errors, a tap goes stale, or a pipeline's volume swings; the recovery agent diagnoses it and — within the agent policy's recovery mode — repairs and verifies it. Each entry carries kind, resource, state (open | diagnosing | proposed | awaiting_approval | executing | verifying | resolved | failed | abandoned), classification, and a step-by-step narrative. Use state=open for what is being worked right now. Returns {enabled:false, incidents:[]} when the recovery agent is off.

Input parameters:

- `limit` (integer): Maximum incidents to return (default 50).
- `state` (string): Filter: open (any active state) or a specific state name. Omit for all.

### `get_incident` (~78 tokens)

Read one recovery-agent incident by id — its trigger, classification, proposal, step-by-step narrative, approvals it is waiting on, and outcome. When the operator asks about a failure the platform is already working, explain THIS record instead of re-diagnosing from scratch.

Input parameters:

- `incident_id` (string, required): The incident id (inc_…).

### `find_data` (~187 tokens)

Find datasets by meaning: ranks the pipelines your key can read against a natural-language query over their names, descriptions, tags, catalogs, destination field names, and source hosts. Each hit returns where the data lives, how fresh it is, provenance handles (latest run id, config version, script sha), lineage, and a `howToQuery` hint naming the existing query/search tool with pre-filled arguments. Discovery only — nothing is executed for you: make the query call yourself, then pass its provenance handles to ai_answer as `sources` so the answer carries them.

Input parameters:

- `ai` (boolean): Rerank the top candidates with the platform's primary AI model (default: false — ranking is deterministic).
- `limit` (integer): Maximum results to return (default: 5, max: 25).
- `query` (string, required): Natural-language description of the data you need.

### `get_provenance` (~166 tokens)

Resolve a stamped `_datris_run_id` value back to its origin: the pipeline run, the tap run that fed it, the script commit, the pipeline config version, and the declared source. Use it when rows or search results carry `_datris_*` provenance fields (pipelines with provenance stamping enabled). Returns one document walking the whole chain.

Input parameters:

- `config_version` (integer): The `_datris_config_version` value from the data, if present.
- `pipeline` (string): Pipeline name, if known (speeds resolution).
- `run_id` (string, required): The `_datris_run_id` value from the data (the pipeline run token).
- `tap_run` (string): The `_datris_tap_run` value from the data, if present.

### `get_lineage` (~309 tokens)

Traverse the lineage graph from one node: everything upstream (what feeds it) and/or downstream (what depends on it) of a source, tap, pipeline, dataset, or catalog, with the edges between them, freshness for the pipeline involved, and optionally the most recent recorded runs (what each run read and wrote, per destination). Datasets a pipeline used to land into under an earlier configuration are marked `historical`. Use it for impact analysis before changing or deleting something — 'what is downstream of this tap?' — or to see which datasets a pipeline actually wrote. Node names: a tap or pipeline name; a dataset's `kind:coordinates` id as returned by find_data or list_pipelines lineage; a source host; a catalog name.

Input parameters:

- `columns` (boolean): For pipeline and dataset nodes, include column-level lineage: which destination columns pass through from which source fields (exact), which the platform adds (system), and any cached AI-inferred map…
- `depth` (integer): Maximum hops from the node (default: unbounded).
- `direction` (string): Which way to traverse (default: both).
- `name` (string, required): The node's name (the part after `type:` in a lineage id).
- `node_type` (string, required): The kind of node to start from.
- `runs` (integer): Include this many most-recent recorded runs for the node (default: 0, max: 50).

## Diagnostics

Captured diagnostic sections: Provenance, Install scripts, Dependencies. The full working is on the page: https://verifymcp.io/servers/datris-datris/datris-mcp-server#diagnostics

## Score history

- 2026-09-21: 79
- 2026-09-20: 78
- 2026-09-19: 78
- 2026-09-18: 62
- 2026-09-17: 77
- 2026-09-16: 77
- 2026-09-15: 76
- 2026-09-14: 76
- 2026-09-13: 75
- 2026-09-12: 75
- 2026-09-11: 74
- 2026-09-10: 59
- 2026-09-09: 73
- 2026-09-08: 58
- 2026-09-07: 72
- 2026-09-06: 72
- 2026-09-05: 71
- 2026-09-04: 71
- 2026-09-03: 70
- 2026-09-02: 55
- 2026-09-01: 40
- 2026-08-31: 40
- 2026-08-30: 40
- 2026-08-29: 40
- 2026-08-28: 40
- 2026-08-27: 40
- 2026-08-26: 40
- 2026-08-25: 40
- 2026-08-24: 40
- 2026-08-23: 40

## Common questions

### What is the Datris MCP server?

Datris is an MCP server listed in the public MCP registry as io.github.datris/datris. The data control plane for AI agents, acquire, validate, land, and query data over MCP. This page covers its PyPI package (datris-mcp-server).

### Is the Datris MCP server safe to use?

Datris scores 79 out of 100 on VerifyMCP. We found no known CVEs affecting it as of 21 September 2026. That is a record of what we were able to check automatically, not an endorsement. The category breakdown on this page shows every signal behind the number, including the ones we could not confirm.

### What tools does the Datris MCP server expose?

Datris exposes 75 tools: list_pipelines, get_pipeline, create_pipeline, set_catalog, delete_pipeline, and 70 more. Their descriptions and schemas cost roughly 17,021 tokens of context every time the server is loaded.

### Is the Datris MCP server still maintained?

Datris is still listed as active in the MCP registry. We last reached this channel on 21 September 2026. Those dates come from our own scans of the registry and the channel itself, not from anything the publisher announced.

### What licence is the Datris MCP server under?

Datris declares the Apache-2.0 licence, which is OSI-approved. That covers the source only, and says nothing about the cost of any service it calls.

## Links

- PyPI project: https://pypi.org/project/datris-mcp-server/
- Socket report: https://socket.dev/pypi/package/datris-mcp-server
- Repository: https://github.com/datris/datris-platform-oss
- Changelog RSS feed: https://verifymcp.io/servers/datris-datris/datris-mcp-server.xml
- Changelog JSON feed: https://verifymcp.io/servers/datris-datris/datris-mcp-server.json
- HTML version of this page: https://verifymcp.io/servers/datris-datris/datris-mcp-server