MCP

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 `Authorization: Bearer` header, depending on the client

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

Install

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

claude mcp add --transport http retab https://mcp.retab.com/mcp

codex mcp add retab --url https://mcp.retab.com/mcp
# OAuth flow opens in your browser; verify with:
codex mcp get retab

{
  "retab": {
    "type": "streamable-http",
    "url": "https://mcp.retab.com/mcp",
    "headers": { "Authorization": "Bearer YOUR_API_KEY" }
  }
}

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 evals

Tool	Use it to
`workflows_evals_create`	Create a workflow eval with one input source (manual handle inputs or a captured run step), one output handle target, and one assertion.
`workflows_evals_list`	List evals with latest-run rollups, assertion outcomes, and schema drift status.
`workflows_evals_get`	Get an eval’s definition, stored inputs, assertion, validation status, and cached latest-run summary.
`workflows_evals_update`	Update an eval’s source and/or assertion.
`workflows_evals_delete`	Delete an eval and its run history.
`workflows_evals_runs_create`	Run one eval, all evals for a workflow, or all evals for a block. Async - returns a run `id`; poll the workflow-eval run for status and results.
`workflows_evals_runs_get`	Fetch a workflow-eval run by `run_id`, including lifecycle, timing, target, and aggregate counts.
`workflows_evals_results_list`	List the eval results produced by one workflow-eval run.
`workflows_evals_results_get`	Fetch one eval result by `result_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`), `evals`, `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.

Overview

Primitives

Workflows

Core Concepts

Enterprise

Install

What you get

Tool reference

Files

Workflows

Workflow blocks

Workflow edges

Workflow runs

Workflow artifacts

Workflow evals

Experiments

Utilities

Prompts

​Install

​What you get

​Tool reference

​Files

​Workflows

​Workflow blocks

​Workflow edges

​Workflow runs

​Workflow artifacts

​Workflow evals

​Experiments

​Utilities

​Prompts

Install

What you get

Tool reference

Files

Workflows

Workflow blocks

Workflow edges

Workflow runs

Workflow artifacts

Workflow evals

Experiments

Utilities

Prompts