> ## Documentation Index > Fetch the complete documentation index at: https://docs.retab.com/llms.txt > Use this file to discover all available pages before exploring further. # 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 `Authorization: Bearer` header, depending on the client | Grab an API key from **Settings → API Keys** in the [dashboard](https://retab.com/dashboard/settings) before you start. ## Install ```sh Recommended theme={null} curl -fsSL https://retab.com/install.sh | sh && retab setup ``` ```sh Claude Code theme={null} claude mcp add --transport http retab https://mcp.retab.com/mcp ``` ```sh Codex theme={null} codex mcp add retab --url https://mcp.retab.com/mcp # OAuth flow opens in your browser; verify with: codex mcp get retab ``` ```json Generic MCP client theme={null} { "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](/workflows/Workflows) and [Blocks](/workflows/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. |