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

# MCP reference

> Connection options, tool scope and paged reads for Flowfield MCP clients.

For a first connection from your editor or terminal, follow [Connect an external agent](https://docs.flowfield.sh/mcp-integration.md). MCP is the supported programmatic interface for agents. The HTTP endpoints used by the bundled app are internal transport, not a separately supported public API.

## Connection

| Setting | Value |
| - | - |
| Transport | Streamable HTTP |
| Default endpoint | `http://127.0.0.1:8765/mcp/` |
| Supported connection helpers | `codex`, `claude-code`, `pi` |
| Default service port | `8765` |

For a different port or connection name, use matching options:

```sh theme={null}
flowfield --port 8770 integration connect claude-code --name flowfield-local
flowfield --port 8770 integration status claude-code --name flowfield-local
flowfield --port 8770 integration disconnect claude-code --name flowfield-local
```

Use the same port and name when disconnecting. See [Disconnect](https://docs.flowfield.sh/mcp-integration.md#disconnect) for which clients are affected.

## Tool scope

An external connection can manage workspaces, projects, documents, tasks, execution and results through the public tools. Pass the workspace and record identifiers requested by each tool's schema. The server's tool descriptions provide the current arguments and response expectations.

Built-in Coordinators manage their assigned workspace and its member projects, plus explicitly service-wide harness, notification and update settings. They cannot switch workspaces or start and stop their own conversation. External clients can create workspaces and control the built-in Coordinator. Workers and Reviewers keep tools scoped to their assigned execution.

Saved application settings and workflows are available through MCP. Appearance, unsent drafts, file pickers and browser/OS notification permission belong to the browser. A Coordinator setting that requires a fresh native session must be changed after the active turn stops, through the GUI or an external agent.

Permission and cleanup tools relay your explicit decisions for the exact request. They do not let an agent infer approval, approve its own permission request or assume a process has stopped.

For updates, use the current revision returned by the relevant read. If another edit changes the record, read it again and reconcile your intended change. Code approval binds to the exact result and candidate being reviewed.

## Configure and recover work

Discover tools and their schemas through MCP; the server supplies current arguments and constraints.

| Area | Starting reads and actions |
| - | - |
| Agent choices | `get_coordinator_settings`, `get_workspace_workers`, `get_task_worker_settings`, `get_reviewer_settings`; matching configuration tools save revision-checked choices. |
| Host setup | `get_harness_settings`, `configure_harness`, `check_harness_setup`; paths affect all workspaces, not native accounts. |
| Result runtimes | `prepare_result_runtime`, `run_result`, `stop_result`, `get_inspection`; `confirm_result_stopped` records explicit human cleanup confirmation. |
| Review recovery | `get_review`, `get_review_attempts`, `get_review_activity`, `retry_review`; cleanup confirmation requires your host inspection. |
| Execution evidence | `get_execution_diff`, `get_execution_patch`, `get_execution_log`, `get_setup_log`; follow returned pages for complete evidence. |

Changing settings does not authorize enabling a paused queue or delivering code. Native permissions and saved-check grants require your explicit authorization; code approval binds to the exact result and candidate.

## Read documents

| Tool | Purpose |
| - | - |
| `list_documents` | List document identities and current revision headers. |
| `search_documents` | Find literal text across current workspace documents. |
| `get_document` | Read metadata and an excerpt of a selected revision. |
| `get_document_text` | Read, outline or search the text of an exact revision. |
| `get_coordinator_guide` | Retrieve installed Coordinator workflow instructions. |

Use the revision returned by a document read or search when requesting its text. `get_document_text` accepts:

| Argument | Meaning |
| - | - |
| `mode` | `read`, `outline` or `search`; defaults to `read`. |
| `revision` | Required document revision. |
| `offset` | Starting character offset; defaults to zero. |
| `end` | Optional exclusive end of the selected range. |
| `limit` | Maximum characters per read, up to 4,000. |
| `query` | Literal text to find in search mode. |

Outline results identify heading ranges. Read a section using its `offset` and `end_offset`, then follow the returned continuation until the section is complete. Offsets count Unicode characters.

`search_documents` returns `next_after` when more document pages remain, including when the current page has no matches. For text reads, copy `next_request` or continue with `next_offset` on the same revision. Workers and Reviewers navigate their assigned sources through `read_context`; required sources must be read fully.

## Read execution measurements

`get_context_metrics` reads numeric prompt, tool and output sizes for one execution. Supply `workspace_id`, `source` and `source_id` from the metrics evidence, then follow `next_after` for additional records.

These values measure UTF-8 payload bytes. Use them to investigate large tool responses, repeated reads and failed requests. Use [Metrics](https://docs.flowfield.sh/metrics.md) for token consumption and estimated cost.

Session instructions, messages and tool outputs are separate measurements. Native output may contain Flowfield tool results, so adding the categories can double-count content. Read the returned coverage information when comparing executions: it identifies unavailable measurements, shortened previews and event limits.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.