---
title: "reducto-beta MCP"
description: "Use Reducto Studio and Contextual Schema Optimization from an MCP-compatible coding agent."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.reducto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# reducto-beta MCP

`reducto-beta` is Reducto's private-beta MCP server. It gives an authenticated coding agent access to Studio pipelines and Contextual Schema Optimization workflows.

> **Note:** `reducto-beta` is separate from the general [Reducto MCP server](/mcp-server). Use the general server to parse, extract, split, classify, or edit individual documents. Use `reducto-beta` to operate Studio pipelines or create and improve extraction configurations with Contextual Schema Optimization.

The name `reducto-beta` is the label you configure in your MCP client. The hosted endpoint is:

```text
https://studio.reducto.ai/api/mcp
```

## Connect

**Claude Code**

```bash
claude mcp add --transport http reducto-beta --scope user https://studio.reducto.ai/api/mcp
```

Run `/mcp` inside Claude Code, select `reducto-beta`, and complete the browser sign-in.

**Codex**

```bash
codex mcp add reducto-beta \
  --url https://studio.reducto.ai/api/mcp \
  --oauth-resource https://studio.reducto.ai/api/mcp

codex mcp login reducto-beta --scopes mcp
```

**Cursor and other clients**

Add a remote MCP server named `reducto-beta`:

```json
{
  "mcpServers": {
    "reducto-beta": {
      "url": "https://studio.reducto.ai/api/mcp"
    }
  }
}
```

Your client should open the Reducto authorization flow when it first connects.

Authentication uses your Reducto Studio account and organization. The server applies the same pipeline access checks as Studio. Switching organizations requires reconnecting or reauthorizing the MCP session.

## Recommended workflow

For Contextual Schema Optimization tasks, the coding agent should:

1. Inspect the current schema or extraction goal and skim representative documents.
2. Explain its understanding of the documents, desired output, and downstream use.
3. Prepare `setup_use_case` or `optimize_schema` with `confirm_and_submit: false`.
4. Show the final inputs and warnings, then ask for explicit confirmation.
5. Submit with `confirm_and_submit: true` only after confirmation.
6. Repeatedly call `get_optimizer_run` with the response's `poll_input` until the run reaches a final status.
7. Read the report from the response and surface every unresolved question, ambiguity, and assumption before recommending the configuration.

Ground truth is optional. If it is missing, the agent should ask once whether expected outputs exist and where to find them, but it should not block the run solely because ground truth is unavailable.

## Tool catalog

### Context and pipeline discovery

| Tool | Purpose | Important inputs |
|---|---|---|
| `get_studio_context` | Show the authenticated organization, Studio deployment, and available tools | None |
| `list_pipelines` | Search, sort, filter, and paginate accessible pipelines | `search`, `page`, `pageSize`, `sortField`, `sortDirection`, `filterProcessorTypes`, `excludeDemo` |
| `get_pipeline` | Return a pipeline with ordered processors and working configurations | `pipelineId` |

### Pipeline management

| Tool | Purpose | Important inputs |
|---|---|---|
| `create_pipeline` | Create a pipeline from `PARSE`, `SPLIT`, `EXTRACT`, `EDIT`, or `CLASSIFY` processor specifications | `name`, `processors[]` |
| `update_pipeline` | Rename a pipeline or update processor names/configurations | `pipelineId`, optional `name`, `processors[]` |
| `upload_file` | Import one HTTPS file or prepare a local-file upload | `pipelineId`, `name`, `sourceUrl` or `localPath`, optional `contentType` |
| `upload_files` | Import or prepare uploads for up to 25 files independently | `pipelineId`, `files[]` |
| `run_pipeline` | Run all terminal processors for existing Studio file IDs | `pipelineId`, `fileIds`, optional completion wait controls |
| `create_share_link` | Create a public link to the current pipeline result snapshot | `pipelineId`, optional `expiry`: `1h`, `1d`, `1w`, or `never` |

The server intentionally does not expose pipeline or processor deletion. `update_pipeline` leaves omitted processors unchanged.

Use these tools only when you intend to operate on a Studio pipeline. Do not create a temporary pipeline for Contextual Schema Optimization setup or schema optimization.

### Contextual Schema Optimization

| Tool | Purpose | Important inputs |
|---|---|---|
| `setup_use_case` | Create a schema and prompt from at least three representative documents and an extraction goal | documents or `workspace_ref`, requirements, `confirm_and_submit` |
| `optimize_schema` | Improve an existing schema/prompt from at least three representative documents | current schema/prompt, documents, optional ground truth, `confirm_and_submit` |
| `health_check` | Coming soon; not available during the current design-partner beta | Do not invoke yet |
| `get_optimizer_run` | Poll one accepted setup or optimization run | `run_id`, optional `workflow` |
| `create_optimizer_workspace_upload` | Create a presigned upload for a native Contextual Schema Optimization workspace ZIP | `workflow`, document counts, result controls |

The `health_check` tool contract may change before release. Reducto will update this page when it is ready to use.

## Provide documents

The MCP accepts three input patterns.

### Local files

Use `local_documents` when the coding agent can read the files directly:

```json
{
  "local_documents": [
    {
      "id": "resume-1",
      "name": "resume-1.pdf",
      "local_path": "/absolute/path/resume-1.pdf",
      "size_bytes": 48213
    }
  ]
}
```

For optimization, pair expected JSON through `local_ground_truth` and set `document_id` to the matching document. A local MCP client packages and uploads the workspace automatically. A hosted client returns a ZIP manifest and presigned upload instructions for the coding agent to complete.

### HTTPS references

Use `document_refs` for public or presigned HTTPS URLs. Setup uses `url`; optimization uses `document_url` and optional `ground_truth_url`. Do not mix HTTPS references with local files in one preparation call.

### Native workspace ZIP

Use `create_optimizer_workspace_upload` when the corpus exceeds 150 MiB, contains many files, or requires transforming a table of expected outputs into per-document `ground_truth.json` files. Upload the returned workspace, then pass its `workspace_ref` to `setup_use_case` or `optimize_schema`.

## Example prompts

### Create a resume extraction configuration

> Use reducto-beta to set up extraction for the resumes in `/path/to/resumes`. I need candidate contact details, work history, education, and skills. Preserve responsibility text verbatim. Inspect a few files, tell me your understanding, and prepare the run for confirmation.

### Improve an existing configuration

> Use reducto-beta to optimize this resume extraction schema against `/path/to/evaluation-set`. Expected JSON is beside each PDF. Focus on missing employment dates and inconsistent responsibility arrays. Do not submit until I confirm the prepared run.

## Results and safety

`get_optimizer_run` returns `accepted`, `running`, `completed`, `partial`, or `failed`. The agent must continue polling through intermediate states and should not present an answer until the run reaches a final status or four hours have passed.

Completed and partial runs include either safe inline artifacts or a temporary result bundle. The agent should inspect the report when instructed and distinguish measured ground-truth accuracy from estimated or consistency-based evidence.

`reducto-beta` does not expose pipeline deletion. Contextual Schema Optimization preparation is non-destructive, but submission creates a billable asynchronous run. The confirmation step exists to make that boundary explicit.

## Troubleshooting

| Problem | What to do |
|---|---|
| The server is missing | Confirm the name is `reducto-beta` and the URL is `https://studio.reducto.ai/api/mcp` |
| Authentication expired | Reconnect the server or rerun your client's MCP login flow |
| The wrong organization is active | Reauthorize using an account with access to the intended Studio organization |
| The agent stopped at `accepted` or `running` | Ask it to keep calling `get_optimizer_run` with the response's `poll_input` |
| The MCP client cannot read local files | Use absolute paths and confirm the MCP client has filesystem access |
| The corpus is larger than 150 MiB | Use `create_optimizer_workspace_upload` and a native workspace ZIP |

Source: https://docs.reducto.ai/contextual-schema-optimization/reducto-beta/index.mdx
