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
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the tap to run | |
| params | No | 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 (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"]} | |
| reason | No | Optional one-line reason for this change, recorded in the platform's audit log and shown to anyone asked to approve it. |