MCP

Connect Retab to Claude, Codex, and any other MCP-compatible client.

Retab exposes its workflow and document tools through an MCP server, so you can build and run document pipelines directly from an MCP client.

Setting	Value
Server name	retab
Transport	streamable-http
Server URL	https://mcp.retab.com/mcp
Authentication	OAuth or an Api-Key header, depending on the client

Grab an API key from Settings → API Keys in the dashboard before you start.

Install

Recommended

curl -fsSL https://retab.com/install.sh | sh && retab setup

Claude Desktop (paid plan required): Settings → Connectors → Add custom connector, name retab, URL https://mcp.retab.com/mcp, complete OAuth.

What you get

Once connected, your MCP client can browse files, build and edit workflows, run them, and iterate on results. Most clients list the tools automatically after connecting — ask your client to “build a workflow from this PDF” to get going.

For the workflow model itself, see Workflows and Blocks.

Tool reference

The server exposes tools grouped under underscore-separated namespaces. Start with help — it returns Retab-specific guidance for whichever subsystem you’re about to use.

Files

Tool	Use it to
files_list	List recent files in the org, optionally filtered by workflow id or filename, with id pagination.
files_upload	Upload a file from a data URL or HTTP(S) URL and get back a durable file_id.
files_analyze	Analyze one document into a Document Blueprint (subdocuments, fields, recommended topology). Async — returns a job_id; poll with jobs_get.
files_grep	Search a literal string or Python regex in one file. Returns matches with a format-specific anchor (page+line for PDFs, line+char for text, sheet+cell for spreadsheets).
files_inspect	Render a specific region of a file — line range, spreadsheet/CSV range, PDF page, or image area — so you can verify a files_grep hit in context.
files_get_sources	Return per-leaf provenance for a completed extraction (each value wrapped as {value, source: {content, anchor}}). Supports path to drill into a subtree of big extractions.

Workflows

Tool	Use it to
workflows_create	Create an empty workflow scaffold with a default start_document block.
workflows_list	List workflows in the org, most-recently-updated first, with id pagination.
workflows_get	Fetch a workflow’s full graph (blocks, configs, positions, handles, edges). In MCP clients that support widgets, this renders an interactive graph.
workflows_diagnose	Check a draft for structural errors and warnings — missing start, dangling edges, unreachable blocks, type mismatches, incomplete configs, human-review gates, cycles.

Workflow blocks

Block tools operate on flat block resources keyed by workflow_id.

Tool	Use it to
workflows_blocks_get	Get a block’s type, label, config, position, parent container, connected edges, and available handles.
workflows_blocks_create	Add a block to a draft. Supports parent_id for placing inside for_each/while_loop containers, connect_from for auto-wired connections, and connections for explicit handle wiring on branching blocks (classifier, split).
workflows_blocks_update	Update a block’s label, config, position, size, or parent. For extract blocks supports surgical json_schema_patch (RFC 6902); for function blocks supports surgical code_patch (exact-string Edit-style). Pass replace=true to replace config entirely.
workflows_blocks_delete	Delete a block and all its connected edges from the draft.

Workflow edges

Edge tools operate on flat edge resources keyed by workflow_id.

Tool	Use it to
workflows_edges_list	List draft edges, optionally filtered by source or target block.
workflows_edges_create	Connect a source block’s output handle to a target block’s input handle. Use workflows_blocks_get first to discover handle names.
workflows_edges_delete	Delete a draft edge.

Workflow runs

Tool	Use it to
workflows_runs_create	Run a workflow against production, draft, or a pinned version id. Inputs map start_document block ids to file_id strings (or {download_url, filename}) and start_json block ids to JSON objects.
workflows_runs_list	List recent runs with lifecycle and timing, optionally filtered by status.
workflows_runs_get	Fetch a run’s lifecycle, timing, inputs, and step summaries. Waits up to 5s for in-progress runs.
workflows_steps_list	List every step in a run with lifecycle, timing, errors, model, and the artifact ref.
workflows_steps_get	Inspect one persisted step object by step_id, including lifecycle, timing, handle inputs, handle outputs, artifact, retry count, and model fields.
workflows_reviews_*	Reviews for gated block runs: list the queue, inspect triggered_by, create corrected versions with parent_id, approve/reject an exact version_id, or wait for a gate to fire.

Workflow artifacts

Tool	Use it to
workflows_artifacts_get	Dereference a step’s {operation, id} artifact ref into the canonical persisted record. Use this to inspect why a conditional branch matched (evaluations, matched_condition_ids, selected_handles) or to read invocation artifacts.
workflows_artifacts_list	List and dereference every artifact produced in one run, optionally filtered by operation or block_id.

Workflow tests

Tool	Use it to
workflows_tests_create	Create a workflow test with one input source (manual handle inputs or a captured run step), one output handle target, and one assertion.
workflows_tests_list	List tests with rollups: passed, failed, blocked, error, cancelled, not_run, and schema_drifted.
workflows_tests_get	Get a test’s definition, stored inputs, assertion, validation status, and cached latest-run summary.
workflows_tests_update	Update a test’s source and/or assertion.
workflows_tests_delete	Delete a test and its run history.
workflows_tests_runs_create	Run one test, all tests for a workflow, or all tests for a block. Async - returns a run id; poll the workflow-test run for status and results.
workflows_tests_runs_get	Fetch a workflow-test run by run_id, including lifecycle, timing, target, and aggregate counts.
workflows_tests_results_list	List the test results produced by one workflow-test run.
workflows_tests_results_get	Fetch one test result from a workflow-test run by run_id and test_id.

Experiments

Tool	Use it to
experiments_create	Attach a consensus experiment to a supported block (extract, split, classifier, split-by-key for_each). Defines a document set; does not run metrics — call experiments_runs_create after.
experiments_list	List experiments on a workflow with the latest run’s status, score, is_stale flag, and merkle-based schema_drift.
experiments_update	Update an experiment’s document set, name, or n_consensus (3 / 5 / 7). Changing any of these invalidates metrics — re-run after.
experiments_delete	Delete an experiment and all its runs.
experiments_runs_create	Refresh an experiment for the current draft config. Reuses fresh successful results and recomputes failed, missing, or stale documents. Async - returns a run id.
experiments_runs_get	Fetch an experiment run by run_id, including lifecycle, timing, score, and document counts.
experiments_results_list	List the per-document results produced by one experiment run.
experiments_results_get	Fetch one experiment result by run_id and document_id.
experiments_metrics_get	Read run-scoped consensus likelihoods across four views: summary, by_document, by_target, and votes.

Utilities

Tool	Use it to
help	Get Retab-specific guidance before touching an unfamiliar subsystem. Topics: default, files, workflows, workflows_runs, workflow_blocks (with optional block_type), tests, experiments, human_review.
jobs_get	Poll generic async jobs from tools such as files_analyze. Waits up to 5s before returning.

Prompts

The server also exposes two MCP prompts (clients with prompt support surface these alongside tools):

Prompt	Purpose
workflow_assistant	Retab workflow assistant prompt for building, configuring, testing, and debugging workflows.
workflow_agent	Full workflow-agent system prompt for external MCP clients.