> For the complete documentation index, see [llms.txt](/llms.txt). Every page on this site is also available as markdown at `<path>.md`.

# MCP

Helpers for exposing Flow AI runtime tools as Model Context Protocol servers.

## Runtime MCP surface

The module helpers below are thin wrappers over methods on the native
[`Runtime`](/docs/reference/runtime) handle: `mcp.list_tools(...)` calls
`runtime.list_mcp_tools(...)`, `mcp.serve_stdio(...)` calls
`runtime.serve_mcp_stdio(...)`, and `mcp.serve_http(...)` calls
`runtime.serve_mcp_http(...)`. Use the runtime methods directly when you
already hold a runtime handle; use `create_mcp_runtime(...)` to build a
minimal MCP-only runtime. The CLI equivalent is
`flowai-harness mcp python MODULE:OBJECT --agent NAME`, which serves over
stdio by default or Streamable HTTP with `--transport streamable-http`.

<span id="flowai_harness.mcp.list_tools"></span>

## `list_tools`

`list_tools(runtime: 'Any', *, agent: 'str', expose_agent_tools: 'bool' = False) -> 'list[dict[str, object]]'`

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>runtime</code></td>
<td><code>Any</code></td>
<td>required</td>
</tr>
<tr>
<td><code>agent</code></td>
<td><code>str</code></td>
<td>required</td>
</tr>
<tr>
<td><code>expose_agent_tools</code></td>
<td><code>bool</code></td>
<td><code>False</code></td>
</tr>
</tbody>
</table>

<p><strong>Returns:</strong> <code>list[dict[str, object]]</code></p>

Return MCP tool metadata for one runtime agent.

Args:
    runtime: A native `Runtime` returned by `create_runtime(...)`.
    agent: Specialist or other runtime agent whose direct tools should be exposed.
    expose_agent_tools: Reserved for future recursive agent tools. Direct MCP serving omits
        those tools by default, and the runtime-generated `agents` toolkit is not supported
        in this mode.

Returns:
    A list of MCP tool descriptors (name, description, input schema) for
    the agent's directly bound tools and toolkit tools.

<span id="flowai_harness.mcp.serve_stdio"></span>

## `serve_stdio`

`serve_stdio(runtime: 'Any', *, agent: 'str', thread_id: 'str | None' = None, call_timeout_secs: 'float' = 30.0, expose_agent_tools: 'bool' = False) -> 'None'`

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>runtime</code></td>
<td><code>Any</code></td>
<td>required</td>
</tr>
<tr>
<td><code>agent</code></td>
<td><code>str</code></td>
<td>required</td>
</tr>
<tr>
<td><code>thread_id</code></td>
<td><code>str | None</code></td>
<td><code>None</code></td>
</tr>
<tr>
<td><code>call_timeout_secs</code></td>
<td><code>float</code></td>
<td><code>30.0</code></td>
</tr>
<tr>
<td><code>expose_agent_tools</code></td>
<td><code>bool</code></td>
<td><code>False</code></td>
</tr>
</tbody>
</table>

<p><strong>Returns:</strong> <code>None</code></p>

Serve one runtime agent's tools over MCP stdio.

This transport is intended for local MCP clients that launch the server as a subprocess.
Python tool callbacks execute in this Python process. The coroutine runs
until the MCP client disconnects.

Args:
    runtime: A native `Runtime` returned by `create_runtime(...)`.
    agent: Runtime agent whose tools are exposed.
    thread_id: Optional fixed thread id used for runtime tool dispatch.
    call_timeout_secs: Per tool-call timeout in seconds.
    expose_agent_tools: Reserved for future recursive agent tools.

<span id="flowai_harness.mcp.serve_http"></span>

## `serve_http`

`serve_http(runtime: 'Any', *, agent: 'str', host: 'str' = '127.0.0.1', port: 'int' = 8765, path: 'str' = '/mcp', transport: 'str' = 'streamable-http', thread_id: 'str | None' = None, call_timeout_secs: 'float' = 30.0, expose_agent_tools: 'bool' = False, allowed_origins: 'list[str] | None' = None, require_origin: 'bool' = True) -> 'None'`

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>runtime</code></td>
<td><code>Any</code></td>
<td>required</td>
</tr>
<tr>
<td><code>agent</code></td>
<td><code>str</code></td>
<td>required</td>
</tr>
<tr>
<td><code>host</code></td>
<td><code>str</code></td>
<td><code>'127.0.0.1'</code></td>
</tr>
<tr>
<td><code>port</code></td>
<td><code>int</code></td>
<td><code>8765</code></td>
</tr>
<tr>
<td><code>path</code></td>
<td><code>str</code></td>
<td><code>'/mcp'</code></td>
</tr>
<tr>
<td><code>transport</code></td>
<td><code>str</code></td>
<td><code>'streamable-http'</code></td>
</tr>
<tr>
<td><code>thread_id</code></td>
<td><code>str | None</code></td>
<td><code>None</code></td>
</tr>
<tr>
<td><code>call_timeout_secs</code></td>
<td><code>float</code></td>
<td><code>30.0</code></td>
</tr>
<tr>
<td><code>expose_agent_tools</code></td>
<td><code>bool</code></td>
<td><code>False</code></td>
</tr>
<tr>
<td><code>allowed_origins</code></td>
<td><code>list[str] | None</code></td>
<td><code>None</code></td>
</tr>
<tr>
<td><code>require_origin</code></td>
<td><code>bool</code></td>
<td><code>True</code></td>
</tr>
</tbody>
</table>

<p><strong>Returns:</strong> <code>None</code></p>

Serve one runtime agent's tools over MCP Streamable HTTP.

The server binds to loopback by default and validates browser `Origin` headers unless
`require_origin=False` is supplied. The coroutine runs until the server
is stopped.

Args:
    runtime: A native `Runtime` returned by `create_runtime(...)`.
    agent: Runtime agent whose tools are exposed.
    host: Host to bind.
    port: Port to bind.
    path: HTTP endpoint path for the MCP server.
    transport: Only `"streamable-http"` is supported.
    thread_id: Optional fixed thread id used for runtime tool dispatch.
    call_timeout_secs: Per tool-call timeout in seconds.
    expose_agent_tools: Reserved for future recursive agent tools.
    allowed_origins: Additional `Origin` header values to accept.
    require_origin: Validate browser `Origin` headers. Disable only for
        non-browser clients on trusted networks.

Raises:
    ValueError: If `transport` is not `"streamable-http"`.
    RuntimeError: If the server fails to bind or serving fails.

<span id="flowai_harness.mcp.create_mcp_runtime"></span>

## `create_mcp_runtime`

`create_mcp_runtime(*, tools: 'list[object] | None' = None, toolkits: 'list[str] | None' = None, agent: 'str' = 'mcp', tenant: 'str' = 'flowai-mcp', data_environment: 'object | None' = None, services: 'object | None' = None) -> 'Any'`

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>tools</code></td>
<td><code>list[object] | None</code></td>
<td><code>None</code></td>
</tr>
<tr>
<td><code>toolkits</code></td>
<td><code>list[str] | None</code></td>
<td><code>None</code></td>
</tr>
<tr>
<td><code>agent</code></td>
<td><code>str</code></td>
<td><code>'mcp'</code></td>
</tr>
<tr>
<td><code>tenant</code></td>
<td><code>str</code></td>
<td><code>'flowai-mcp'</code></td>
</tr>
<tr>
<td><code>data_environment</code></td>
<td><code>object | None</code></td>
<td><code>None</code></td>
</tr>
<tr>
<td><code>services</code></td>
<td><code>object | None</code></td>
<td><code>None</code></td>
</tr>
</tbody>
</table>

<p><strong>Returns:</strong> <code>Any</code></p>

Build a minimal runtime for MCP-only tool serving.

The helper creates one specialist named by `agent` under the supplied tenant and attaches
the supplied Python tools or built-in toolkit ids. The runtime uses the
`"noop"` interpreter, so no provider credentials are needed.

Args:
    tools: `ToolSpec` values with Python handlers to expose.
    toolkits: Built-in toolkit ids to expose.
    agent: Name of the generated specialist agent.
    tenant: Tenant resource id for the generated runtime.
    data_environment: Rust-owned toolkit dependencies such as catalogs
        and target databases. If it includes `tenant_id`, it must match
        `tenant`.
    services: Python-owned objects needed by custom tool callbacks.

Returns:
    A native `Runtime` handle ready for `serve_stdio(...)`,
    `serve_http(...)`, or `list_tools(...)`.