Skip to main content
Glama
Datris MCP Server

Datris MCP Server

run_tap

Triggers a tap script to ingest source data and hand records to its configured pipeline for loading. Use it to start a full or parameterized run, then poll pipeline status to confirm completion.

Instructions

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 destination before that. For a Live Read (scratch) pipeline (nothing landed), read the rows off the rollup's resultPreview and resultTruncated; call get_pipeline_result only when resultTruncated is true. • persisted: false → the destination was NOT written. Read persistedReason: - no_target_pipeline: tap has no pipeline wired. Tell the user; offer to call update_tap. - test_mode: ran in test mode (or mcp-server/datris version mismatch). Flag it; do not report data as stored. - run_error: show the error string. If the error says the payload exceeded the disk budget (it names PIPELINE_MAX_PAYLOAD_MB), tell the user the operator can raise that variable; as a one-off alternative, reduce the source range via params and call run_tap again — multiple runs all land in the same destination pipeline. If the error says the run timed out (it names TAP_RUN_TIMEOUT_SECONDS), tell the user the operator can raise that variable; as a one-off alternative, chunk the source range via params. A run that timed out returns the script's logs, its [wrapper] streamed N records progress lines and a partial record count. Read them first: a script that reached the source and was still streaming records when the timeout hit is healthy and too long, not wrong — do not rewrite it; tell the user how far it got and offer a smaller window via params or the operator's timeout setting. For a recurring tap, the durable fix is making the script incremental via DATRIS_TAP_STATE (see the tap-workflow-reference resource). VOLUME RULE: one run handles multi-GB payloads — records stream to disk, never through memory. Do NOT split a source into several runs, cap a run at N rows, or build resume-from-destination logic because you think the output is too big. Fetch the whole requested range in one run, unless the estimate below exceeds a budget and the user has chosen chunking — that is the one size-driven exception. Chunk otherwise only when the source API pages natively or when the user explicitly asks for a bounded window. SIZING RULE: before a first run on a large source, call get_version for the budgets in force, then estimate staged disk as ≈ 26 bytes × column count per record × rows against PIPELINE_MAX_PAYLOAD_MB (the value in force is pipelineMaxPayloadMB from get_version; default 4096 MB, 0 = unlimited), and script time as rows ÷ 15,000 per second when fetch() emits one record at a time or rows ÷ 90,000 per second when it emits batches against TAP_RUN_TIMEOUT_SECONDS (tapRunTimeoutSeconds from get_version; default 3600 s). Name the rate used, recommend batches above about a million rows, show the user the rows, bytes/record, GB staged, minutes table, and ask before running when either estimate is over budget. - no_records: source returned nothing. - debounced: this tap was triggered server-side within the last 5 seconds. Do NOT retry — your previous call is still running. Use get_tap_logs to find the live run's publisherToken, then poll get_pipeline_status. - already_running (response status: skipped): another run_tap for this tap is already in flight in this agent session. Same handling as debounced: wait, then look up the live run in get_tap_logs. The response's publisherToken covers every ingestion job this run submitted (structured taps = 1, document taps = N). One get_pipeline_status call with the publisherToken sees them all. 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.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "name": "<name>"
    },
    "name": "run_tap"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameYesName of the tap to run
paramsNoOptional 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 (those belong in the tap secret). Keys must match [A-Za-z_][A-Za-z0-9_]*. Values are stringified; nested objects/arrays are JSON-encoded. Scheduled cron runs supply no params, so scripts must apply sensible defaults when the env var is absent. Example: {"start_date": "2026-05-01", "end_date": "2026-05-31", "ids": ["A001", "B002"]}
reasonNoOptional one-line reason for this change, recorded in the platform's audit log and shown to anyone asked to approve it.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations supplied, the description carries the full burden and does so: it enumerates the response fields (`recordCount`, `publisherToken`, `pipelineTokens`, `persisted`, `persistedReason`, `logs`) and explicitly says records are NOT returned. It discloses the async hand-off, the full `persisted: false` reason taxonomy with per-reason handling, the approval-policy path (`pending_approval` + `approvalId`), and the debounce/already-running semantics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose and test-first rule are correctly front-loaded, and the bulleted `persisted: true/false` branches are scannable. But the description is very long and includes material that reads like server-instruction policy (it even cross-references 'the VALIDATION RULE in the server instructions' while restating that rule), plus an extended sizing/volume discourse that a caller needs only on large sources. Valuable content, but not tightly bounded for a three-parameter tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description must — and does — describe the return shape and what is absent from it, along with the required follow-up chain (`get_pipeline_status` with `publisherToken`, polling `rollup.allDone`, reading `resultPreview` for scratch pipelines). Given the async pipeline hand-off and approval path, this is complete enough for an agent to act correctly after the call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so `name`, `params`, and `reason` are already documented; the description nevertheless adds operational meaning the schema only hints at — that keys become `DATRIS_TAP_PARAM_<key>` env vars, that values are stringified/JSON-encoded, and a strong negative rule (do not rewrite the tap secret for per-run values, because it clobbers concurrent runs and pollutes audit history). The sizing rule's use of `params` for chunking adds further concrete guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ('Manually trigger a tap') and immediately scopes behavior ('Executes the script; when a target pipeline is configured, hands records to the pipeline async'). It explicitly distinguishes itself from the sibling `test_tap` ('If you need to preview what the script produces, call `test_tap` instead'), so an agent can route between preview and real execution without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

States a hard precondition (must have called `test_tap` and seen success before the first run of a new/updated tap), names the consequence of skipping it, and points to alternatives for per-run values (use `params`, not secret rewriting; update the script via `create_tap` for new params). It also gives explicit when-not guidance ('do NOT retry' on `debounced`, 'do not split a source into several runs'), which is the kind of routing an agent would otherwise get wrong.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools