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

# harnest.mcp

> Public Python signatures, fields, and methods.

[All Python modules](https://usefused.com/docs/harnest/reference/api/overview.md) · [Import and compatibility guidance](https://usefused.com/docs/harnest/build/python-imports.md)

## Discovery operations

The facade also exposes `inspect()`, `list_tools(cursor=None)`, `list_resources(cursor=None)`, `list_resource_templates(cursor=None)`, `list_prompts(cursor=None)`, and `get_prompt(name, arguments=None)`. Inspection and tool-catalogue listing are developer operations, not additional model tools.

## Exports

| Name | Kind |
| - | - |
| [`MCPClient`](#mcpclient) | Class |
| [`MCPClientContext`](#mcpclientcontext) | Class |
| [`MCPClientLifecycle`](#mcpclientlifecycle) | Class |
| [`MCPClientUnavailableError`](#mcpclientunavailableerror) | Class |
| [`MCPContext`](#mcpcontext) | Class |
| [`MCPContextUnavailableError`](#mcpcontextunavailableerror) | Class |
| [`MCPHTTPClientOptions`](#mcphttpclientoptions) | Class |
| [`MCPLifecycleError`](#mcplifecycleerror) | Class |
| [`MCPLifecyclePipeline`](#mcplifecyclepipeline) | Class |
| [`MCPResourceClient`](#mcpresourceclient) | Class |
| [`MCPResourceError`](#mcpresourceerror) | Class |
| [`MCPResourceEvent`](#mcpresourceevent) | Class |
| [`MCPSubscription`](#mcpsubscription) | Class |
| [`MCPToolCallError`](#mcptoolcallerror) | Class |
| [`MCPToolCallRequest`](#mcptoolcallrequest) | Class |
| [`MCPToolLifecycleContext`](#mcptoollifecyclecontext) | Class |
| [`MCPToolUnavailableError`](#mcptoolunavailableerror) | Class |
| [`ManagedMCPClient`](#managedmcpclient) | Class |

## MCPClient

A client connection to a stdio, SSE, or Streamable HTTP MCP server.

Obtain this object from the owning Harnest API; its constructor includes runtime bindings.

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `transport` | `str` | `—` |
| `command` | `str \| None` | `None` |
| `args` | `Sequence[str]` | `tuple()` |
| `env` | `Mapping[str, str]` | `dict()` |
| `url` | `str \| None` | `None` |
| `headers` | `Mapping[str, str]` | `dict()` |
| `tool_filter` | `Sequence[str] \| None` | `None` |
| `tool_name_prefix` | `str \| None` | `None` |
| `timeout_seconds` | `float` | `30` |
| `sse_read_timeout_seconds` | `float` | `300` |
| `approval` | `ApprovalPolicy \| None` | `None` |
| `identity` | `str \| None` | `None` |
| `capability_id` | `str \| None` | `None` |
| `lifecycle` | `MCPClientLifecycle \| None` | `None` |
| `cwd` | `str \| None` | `None` |
| `portable` | `Any` | `None` |
| `permission` | `str \| None` | `None` |
| `tool_permissions` | `Mapping[str, str]` | `dict()` |
| `resources` | `Sequence[str] \| None` | `None` |
| `prompts` | `Sequence[str] \| None` | `None` |
| `max_content_bytes` | `int` | `1048576` |
| `subscriptions` | `Sequence[MCPSubscription]` | `tuple()` |

> [accordion] Example
>
> ```python theme={null}
> from harnest.mcp import MCPClient
>
> client: MCPClient  # returned by Harnest, not constructed directly
> ```

### MCPClient.from\_openapi

```python theme={null}
MCPClient.from_openapi(
    source: str | Path,
    *,
    base_url: str | None = None,
    headers: Mapping[str, str] | None = None,
    **client_options: Any,
) -> 'MCPClient'
```

Connect to a local or remote spec through a runtime OpenAPI bridge.

Reading and conversion happen when the MCP connection opens, never
during authoring or compilation. Use a path relative to `__file__`
for specs bundled with an agent. Headers support `${VARIABLE}`.
`client_options` accepts the standard `stdio` policy options.
Requires the optional `harnest[openapi]` runtime dependency.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `source` | `str \| Path` | Required |
> | `base_url` | `str \| None` | `None` |
> | `headers` | `Mapping[str, str] \| None` | `None` |
> | `**client_options` | `Any` | Optional |
>
> ```python theme={null}
> from harnest.mcp import MCPClient
>
> client = MCPClient.from_openapi(source=...)
> ```

### MCPClient.stdio

```python theme={null}
MCPClient.stdio(
    command: str,
    *args: str,
    env: Mapping[str, str] | None = None,
    tools: Sequence[str] | None = None,
    prefix: str | None = None,
    permission: str | None = None,
    tool_permissions: Mapping[str, str] | None = None,
    timeout_seconds: float = 30,
    lifecycle: MCPClientLifecycle | None = None,
    resources: Sequence[str] | None = None,
    prompts: Sequence[str] | None = None,
    max_content_bytes: int = 1048576,
    subscriptions: Sequence[MCPSubscription] = (),
) -> 'MCPClient'
```

Create an MCP client that starts and communicates with a subprocess.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `command` | `str` | Required |
> | `*args` | `str` | Optional |
> | `env` | `Mapping[str, str] \| None` | `None` |
> | `tools` | `Sequence[str] \| None` | `None` |
> | `prefix` | `str \| None` | `None` |
> | `permission` | `str \| None` | `None` |
> | `tool_permissions` | `Mapping[str, str] \| None` | `None` |
> | `timeout_seconds` | `float` | `30` |
> | `lifecycle` | `MCPClientLifecycle \| None` | `None` |
> | `resources` | `Sequence[str] \| None` | `None` |
> | `prompts` | `Sequence[str] \| None` | `None` |
> | `max_content_bytes` | `int` | `1048576` |
> | `subscriptions` | `Sequence[MCPSubscription]` | `()` |
>
> ```python theme={null}
> from harnest.mcp import MCPClient
>
> client = MCPClient.stdio(command=...)
> ```

### MCPClient.streamable\_http

```python theme={null}
MCPClient.streamable_http(
    url: str,
    *,
    headers: Mapping[str, str] | None = None,
    tools: Sequence[str] | None = None,
    prefix: str | None = None,
    permission: str | None = None,
    tool_permissions: Mapping[str, str] | None = None,
    timeout_seconds: float = 30,
    sse_read_timeout_seconds: float = 300,
    lifecycle: MCPClientLifecycle | None = None,
    resources: Sequence[str] | None = None,
    prompts: Sequence[str] | None = None,
    max_content_bytes: int = 1048576,
    subscriptions: Sequence[MCPSubscription] = (),
) -> 'MCPClient'
```

Create an MCP client using the Streamable HTTP transport.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `url` | `str` | Required |
> | `headers` | `Mapping[str, str] \| None` | `None` |
> | `tools` | `Sequence[str] \| None` | `None` |
> | `prefix` | `str \| None` | `None` |
> | `permission` | `str \| None` | `None` |
> | `tool_permissions` | `Mapping[str, str] \| None` | `None` |
> | `timeout_seconds` | `float` | `30` |
> | `sse_read_timeout_seconds` | `float` | `300` |
> | `lifecycle` | `MCPClientLifecycle \| None` | `None` |
> | `resources` | `Sequence[str] \| None` | `None` |
> | `prompts` | `Sequence[str] \| None` | `None` |
> | `max_content_bytes` | `int` | `1048576` |
> | `subscriptions` | `Sequence[MCPSubscription]` | `()` |
>
> ```python theme={null}
> from harnest.mcp import MCPClient
>
> client = MCPClient.streamable_http(url=...)
> ```

### MCPClient.sse

```python theme={null}
MCPClient.sse(
    url: str,
    *,
    headers: Mapping[str, str] | None = None,
    tools: Sequence[str] | None = None,
    prefix: str | None = None,
    permission: str | None = None,
    tool_permissions: Mapping[str, str] | None = None,
    timeout_seconds: float = 30,
    sse_read_timeout_seconds: float = 300,
    lifecycle: MCPClientLifecycle | None = None,
    resources: Sequence[str] | None = None,
    prompts: Sequence[str] | None = None,
    max_content_bytes: int = 1048576,
    subscriptions: Sequence[MCPSubscription] = (),
) -> 'MCPClient'
```

Create an MCP client using the legacy HTTP/SSE transport.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `url` | `str` | Required |
> | `headers` | `Mapping[str, str] \| None` | `None` |
> | `tools` | `Sequence[str] \| None` | `None` |
> | `prefix` | `str \| None` | `None` |
> | `permission` | `str \| None` | `None` |
> | `tool_permissions` | `Mapping[str, str] \| None` | `None` |
> | `timeout_seconds` | `float` | `30` |
> | `sse_read_timeout_seconds` | `float` | `300` |
> | `lifecycle` | `MCPClientLifecycle \| None` | `None` |
> | `resources` | `Sequence[str] \| None` | `None` |
> | `prompts` | `Sequence[str] \| None` | `None` |
> | `max_content_bytes` | `int` | `1048576` |
> | `subscriptions` | `Sequence[MCPSubscription]` | `()` |
>
> ```python theme={null}
> from harnest.mcp import MCPClient
>
> client = MCPClient.sse(url=...)
> ```

### MCPClient.connect

```python theme={null}
MCPClient.connect(*, framework: Literal['adk', 'langgraph'] = 'langgraph') -> Any
```

Open a developer-owned read client using the configured lifecycle and credentials.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `framework` | `Literal['adk', 'langgraph']` | `'langgraph'` |
>
> ```python theme={null}
> from harnest.mcp import MCPClient
>
> client: MCPClient
> result = client.connect()
> ```

### MCPClient.required\_permissions\_for

```python theme={null}
MCPClient.required_permissions_for(tool_name: str) -> frozenset[str]
```

Combine an optional client requirement with one remote-tool requirement.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `tool_name` | `str` | Required |
>
> ```python theme={null}
> from harnest.mcp import MCPClient
>
> client: MCPClient
> result = client.required_permissions_for(tool_name=...)
> ```

### MCPClient.to\_adk\_toolset

```python theme={null}
MCPClient.to_adk_toolset() -> Any
```

Use native transport while preserving portable expansion and failure rules.

> [accordion] Example
>
> ```python theme={null}
> from harnest.mcp import MCPClient
>
> client: MCPClient
> result = client.to_adk_toolset()
> ```

### MCPClient.to\_langgraph\_connection

```python theme={null}
MCPClient.to_langgraph_connection() -> dict[str, Any]
```

Return a LangChain MCP adapter connection without opening it.

> [accordion] Example
>
> ```python theme={null}
> from harnest.mcp import MCPClient
>
> client: MCPClient
> result = client.to_langgraph_connection()
> ```

## MCPClientContext

Privacy-safe identity supplied to an MCP client lifecycle.

```python theme={null}
MCPClientContext(
    name: str,
    transport: Literal['stdio', 'sse', 'streamable-http'],
    framework: MCPFramework,
    url: str,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `name` | `str` | `—` |
| `transport` | `Literal['stdio', 'sse', 'streamable-http']` | `—` |
| `framework` | `MCPFramework` | `—` |
| `url` | `str` | `—` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `name` | `str` | Required |
> | `transport` | `Literal['stdio', 'sse', 'streamable-http']` | Required |
> | `framework` | `MCPFramework` | Required |
> | `url` | `str` | Required |
>
> ```python theme={null}
> from harnest.mcp import MCPClientContext
>
> context = MCPClientContext(name=..., transport=..., framework=..., url=...)
> ```

## MCPClientLifecycle

Customize one remote MCP connection's HTTP client lifecycle.

`start` and `close` run once for the compiled application. The
synchronous `create_http_client` hook runs for every MCP session because
ADK and LangGraph own and close those session-scoped HTTP clients.

```python theme={null}
MCPClientLifecycle()
```

> [accordion] Example
>
> ```python theme={null}
> from harnest.mcp import MCPClientLifecycle
>
> lifecycle = MCPClientLifecycle()
> ```

### MCPClientLifecycle.start

```python theme={null}
MCPClientLifecycle.start(context: MCPClientContext) -> MCPLifecycleValue
```

Initialize credential, certificate, or gateway support resources.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `context` | `MCPClientContext` | Required |
>
> ```python theme={null}
> from harnest.mcp import MCPClientLifecycle
>
> lifecycle: MCPClientLifecycle
> result = lifecycle.start(context=...)
> ```

### MCPClientLifecycle.create\_http\_client

```python theme={null}
MCPClientLifecycle.create_http_client(options: MCPHTTPClientOptions, context: MCPClientContext) -> Any
```

Return a proxy-aware `httpx.AsyncClient` with safe diagnostics.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `options` | `MCPHTTPClientOptions` | Required |
> | `context` | `MCPClientContext` | Required |
>
> ```python theme={null}
> from harnest.mcp import MCPClientLifecycle
>
> lifecycle: MCPClientLifecycle
> result = lifecycle.create_http_client(options=..., context=...)
> ```

### MCPClientLifecycle.close

```python theme={null}
MCPClientLifecycle.close(context: MCPClientContext) -> MCPLifecycleValue
```

Release application-level resources created by `start`.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `context` | `MCPClientContext` | Required |
>
> ```python theme={null}
> from harnest.mcp import MCPClientLifecycle
>
> lifecycle: MCPClientLifecycle
> result = lifecycle.close(context=...)
> ```

## MCPClientUnavailableError

Raised when an invocation cannot access a named managed MCP client.

> [accordion] Example
>
> ```python theme={null}
> from harnest.mcp import MCPClientUnavailableError
>
> try:
>     ...
> except MCPClientUnavailableError as error:
>     ...
> ```

## MCPContext

Resolve managed MCP clients without exposing the client registry.

```python theme={null}
MCPContext()
```

> [accordion] Example
>
> ```python theme={null}
> from harnest.mcp import MCPContext
>
> context = MCPContext()
> ```

### MCPContext.**call**

```python theme={null}
MCPContext.__call__(name: str) -> ManagedMCPClient
```

Return one named managed client for concise context access.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `name` | `str` | Required |
>
> ```python theme={null}
> from harnest.mcp import MCPContext
>
> context: MCPContext
> client = context(name=...)
> ```

### MCPContext.client

```python theme={null}
MCPContext.client(name: str) -> ManagedMCPClient
```

Return one named client or fail without enumerating capabilities.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `name` | `str` | Required |
>
> ```python theme={null}
> from harnest.mcp import MCPContext
>
> context: MCPContext
> client = context.client(name=...)
> ```

## MCPContextUnavailableError

Raised when managed MCP access has no active invocation binding.

> [accordion] Example
>
> ```python theme={null}
> from harnest.mcp import MCPContextUnavailableError
>
> try:
>     ...
> except MCPContextUnavailableError as error:
>     ...
> ```

## MCPHTTPClientOptions

Adapter-provided inputs for one MCP HTTP client instance.

```python theme={null}
MCPHTTPClientOptions(headers: Mapping[str, str], timeout: Any = None, auth: Any = None) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `headers` | `Mapping[str, str]` | `—` |
| `timeout` | `Any` | `None` |
| `auth` | `Any` | `None` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `headers` | `Mapping[str, str]` | Required |
> | `timeout` | `Any` | `None` |
> | `auth` | `Any` | `None` |
>
> ```python theme={null}
> from harnest.mcp import MCPHTTPClientOptions
>
> options = MCPHTTPClientOptions(headers=...)
> ```

## MCPLifecycleError

An MCP interceptor returned invalid or ambiguous control flow.

> [accordion] Example
>
> ```python theme={null}
> from harnest.mcp import MCPLifecycleError
>
> try:
>     ...
> except MCPLifecycleError as error:
>     ...
> ```

## MCPLifecyclePipeline

Apply explicit portable interceptors around one managed MCP call.

```python theme={null}
MCPLifecyclePipeline(listeners: Sequence[LifecycleListener]) -> None
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `listeners` | `Sequence[LifecycleListener]` | Required |
>
> ```python theme={null}
> from harnest.mcp import MCPLifecyclePipeline
>
> pipeline = MCPLifecyclePipeline(listeners=...)
> ```

### MCPLifecyclePipeline.run

```python theme={null}
async MCPLifecyclePipeline.run(
    request: MCPToolCallRequest,
    handler: Callable[[MCPToolCallRequest], Awaitable[Any]],
    context: MCPToolLifecycleContext,
) -> _MCPExecution
```

Run one call, allowing explicit short-circuit and safe recovery.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `request` | `MCPToolCallRequest` | Required |
> | `handler` | `Callable[[MCPToolCallRequest], Awaitable[Any]]` | Required |
> | `context` | `MCPToolLifecycleContext` | Required |
>
> ```python theme={null}
> from harnest.mcp import MCPLifecyclePipeline
>
> pipeline: MCPLifecyclePipeline
> execution = await pipeline.run(request=..., handler=..., context=...)
> ```

## MCPResourceClient

Connection-bound read API; resource data never becomes system instructions.

```python theme={null}
MCPResourceClient(configured: Any, *, framework: str = 'langgraph') -> None
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `configured` | `Any` | Required |
> | `framework` | `str` | `'langgraph'` |
>
> ```python theme={null}
> from harnest.mcp import MCPResourceClient
>
> client = MCPResourceClient(configured=...)
> ```

### MCPResourceClient.inspect

```python theme={null}
async MCPResourceClient.inspect() -> dict[str, Any]
```

Discover capability metadata without reading resources or rendering prompts.

> [accordion] Example
>
> ```python theme={null}
> from harnest.mcp import MCPResourceClient
>
> client: MCPResourceClient
> result = await client.inspect()
> ```

### MCPResourceClient.list\_tools

```python theme={null}
async MCPResourceClient.list_tools(cursor: str | None = None) -> dict[str, Any]
```

List one page of remote tool schemas under the configured tool policy.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `cursor` | `str \| None` | `None` |
>
> ```python theme={null}
> from harnest.mcp import MCPResourceClient
>
> client: MCPResourceClient
> result = await client.list_tools()
> ```

### MCPResourceClient.list\_resources

```python theme={null}
async MCPResourceClient.list_resources(cursor: str | None = None) -> dict[str, Any]
```

Return one bounded page with the server's opaque nextCursor unchanged.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `cursor` | `str \| None` | `None` |
>
> ```python theme={null}
> from harnest.mcp import MCPResourceClient
>
> client: MCPResourceClient
> result = await client.list_resources()
> ```

### MCPResourceClient.list\_resource\_templates

```python theme={null}
async MCPResourceClient.list_resource_templates(cursor: str | None = None) -> dict[str, Any]
```

Discover parameterized resource URIs without fetching their contents.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `cursor` | `str \| None` | `None` |
>
> ```python theme={null}
> from harnest.mcp import MCPResourceClient
>
> client: MCPResourceClient
> result = await client.list_resource_templates()
> ```

### MCPResourceClient.list\_prompts

```python theme={null}
async MCPResourceClient.list_prompts(cursor: str | None = None) -> dict[str, Any]
```

Discover prompt descriptions and declared arguments.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `cursor` | `str \| None` | `None` |
>
> ```python theme={null}
> from harnest.mcp import MCPResourceClient
>
> client: MCPResourceClient
> result = await client.list_prompts()
> ```

### MCPResourceClient.read\_resource

```python theme={null}
async MCPResourceClient.read_resource(uri: str) -> dict[str, Any]
```

Read an explicitly selected URI through MCP, never through a local file API.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `uri` | `str` | Required |
>
> ```python theme={null}
> from harnest.mcp import MCPResourceClient
>
> client: MCPResourceClient
> result = await client.read_resource(uri=...)
> ```

### MCPResourceClient.get\_prompt

```python theme={null}
async MCPResourceClient.get_prompt(name: str, arguments: Mapping[str, str] | None = None) -> dict[str, Any]
```

Retrieve prompt messages as untrusted data for explicit caller use.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `name` | `str` | Required |
> | `arguments` | `Mapping[str, str] \| None` | `None` |
>
> ```python theme={null}
> from harnest.mcp import MCPResourceClient
>
> client: MCPResourceClient
> result = await client.get_prompt(name=...)
> ```

## MCPResourceError

An MCP capability request failed without exposing connection credentials.

> [accordion] Example
>
> ```python theme={null}
> from harnest.mcp import MCPResourceError
>
> try:
>     ...
> except MCPResourceError as error:
>     ...
> ```

## MCPResourceEvent

One retained resource value; handlers decide whether to invoke an agent or task.

```python theme={null}
MCPResourceEvent(
    client_name: str,
    uri: str,
    resource: Mapping[str, Any],
    reason: Literal['start', 'update', 'reconnect'] = 'update',
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `client_name` | `str` | `—` |
| `uri` | `str` | `—` |
| `resource` | `Mapping[str, Any]` | `—` |
| `reason` | `Literal['start', 'update', 'reconnect']` | `'update'` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `client_name` | `str` | Required |
> | `uri` | `str` | Required |
> | `resource` | `Mapping[str, Any]` | Required |
> | `reason` | `Literal['start', 'update', 'reconnect']` | `'update'` |
>
> ```python theme={null}
> from harnest.mcp import MCPResourceEvent
>
> event = MCPResourceEvent(client_name=..., uri=..., resource=...)
> ```

## MCPSubscription

Opt in to a URI, an async application handler, and explicit recovery policy.

```python theme={null}
MCPSubscription(
    uri: str,
    handler: Callable[[MCPResourceEvent], Awaitable[None]],
    method: Literal['resources/subscribe', 'subscriptions/listen'] = 'resources/subscribe',
    read_on_start: bool = True,
    read_on_reconnect: bool = True,
    handler_timeout_seconds: float = 30,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `uri` | `str` | `—` |
| `handler` | `Callable[[MCPResourceEvent], Awaitable[None]]` | `—` |
| `method` | `Literal['resources/subscribe', 'subscriptions/listen']` | `'resources/subscribe'` |
| `read_on_start` | `bool` | `True` |
| `read_on_reconnect` | `bool` | `True` |
| `handler_timeout_seconds` | `float` | `30` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `uri` | `str` | Required |
> | `handler` | `Callable[[MCPResourceEvent], Awaitable[None]]` | Required |
> | `method` | `Literal['resources/subscribe', 'subscriptions/listen']` | `'resources/subscribe'` |
> | `read_on_start` | `bool` | `True` |
> | `read_on_reconnect` | `bool` | `True` |
> | `handler_timeout_seconds` | `float` | `30` |
>
> ```python theme={null}
> from harnest.mcp import MCPSubscription
>
> subscription = MCPSubscription(uri=..., handler=...)
> ```

## MCPToolCallError

A provider-neutral failure from a discovered managed MCP tool.

> [accordion] Example
>
> ```python theme={null}
> from harnest.mcp import MCPToolCallError
>
> try:
>     ...
> except MCPToolCallError as error:
>     ...
> ```

## MCPToolCallRequest

Opaque remote arguments that a before hook may explicitly replace.

```python theme={null}
MCPToolCallRequest(arguments: Mapping[str, Any] = ...) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `arguments` | `Mapping[str, Any]` | `dict()` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `arguments` | `Mapping[str, Any]` | `...` |
>
> ```python theme={null}
> from harnest.mcp import MCPToolCallRequest
>
> request = MCPToolCallRequest()
> ```

## MCPToolLifecycleContext

Privacy-safe identity for one governed remote-tool execution.

```python theme={null}
MCPToolLifecycleContext(
    framework: str,
    agent_name: str,
    invocation_id: str,
    user_id: str,
    session_id: str,
    client_name: str,
    tool_name: str,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `framework` | `str` | `—` |
| `agent_name` | `str` | `—` |
| `invocation_id` | `str` | `—` |
| `user_id` | `str` | `—` |
| `session_id` | `str` | `—` |
| `client_name` | `str` | `—` |
| `tool_name` | `str` | `—` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `framework` | `str` | Required |
> | `agent_name` | `str` | Required |
> | `invocation_id` | `str` | Required |
> | `user_id` | `str` | Required |
> | `session_id` | `str` | Required |
> | `client_name` | `str` | Required |
> | `tool_name` | `str` | Required |
>
> ```python theme={null}
> from harnest.mcp import MCPToolLifecycleContext
>
> context = MCPToolLifecycleContext(
>     framework=...,
>     agent_name=...,
>     invocation_id=...,
>     user_id=...,
>     session_id=...,
>     client_name=...,
>     tool_name=...,
> )
> ```

### MCPToolLifecycleContext.next

```python theme={null}
MCPToolLifecycleContext.next(replacement: Any = UNCHANGED) -> Next[Any]
```

Continue normally or pass a replacement to the next interceptor.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `replacement` | `Any` | `UNCHANGED` |
>
> ```python theme={null}
> from harnest.mcp import MCPToolLifecycleContext
>
> context: MCPToolLifecycleContext
> result = context.next()
> ```

### MCPToolLifecycleContext.finish

```python theme={null}
MCPToolLifecycleContext.finish(result: ResultT) -> Finish[ResultT]
```

Return a final value without advancing to later execution.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `result` | `ResultT` | Required |
>
> ```python theme={null}
> from harnest.mcp import MCPToolLifecycleContext
>
> context: MCPToolLifecycleContext
> result = context.finish(result=...)
> ```

## MCPToolUnavailableError

Raised when a managed MCP client does not expose a requested tool.

> [accordion] Example
>
> ```python theme={null}
> from harnest.mcp import MCPToolUnavailableError
>
> try:
>     ...
> except MCPToolUnavailableError as error:
>     ...
> ```

## ManagedMCPClient

Named MCP facade with no access to credentials or raw transports.

Obtain this object from the owning Harnest API; its constructor includes runtime bindings.

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `name` | `str` | `—` |

> [accordion] Example
>
> ```python theme={null}
> from harnest.mcp import ManagedMCPClient
>
> client: ManagedMCPClient  # returned by Harnest, not constructed directly
> ```

### ManagedMCPClient.inspect

```python theme={null}
async ManagedMCPClient.inspect() -> Any
```

Discover bounded MCP catalogues through the invocation's governed path.

> [accordion] Example
>
> ```python theme={null}
> from harnest.mcp import ManagedMCPClient
>
> client: ManagedMCPClient
> result = await client.inspect()
> ```

### ManagedMCPClient.list\_resources

```python theme={null}
async ManagedMCPClient.list_resources(cursor: str | None = None) -> Any
```

List one resource page without reading its contents.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `cursor` | `str \| None` | `None` |
>
> ```python theme={null}
> from harnest.mcp import ManagedMCPClient
>
> client: ManagedMCPClient
> result = await client.list_resources()
> ```

### ManagedMCPClient.list\_tools

```python theme={null}
async ManagedMCPClient.list_tools(cursor: str | None = None) -> Any
```

List remote tool metadata within this invocation's permission scope.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `cursor` | `str \| None` | `None` |
>
> ```python theme={null}
> from harnest.mcp import ManagedMCPClient
>
> client: ManagedMCPClient
> result = await client.list_tools()
> ```

### ManagedMCPClient.list\_resource\_templates

```python theme={null}
async ManagedMCPClient.list_resource_templates(cursor: str | None = None) -> Any
```

List one page of parameterized resource URIs.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `cursor` | `str \| None` | `None` |
>
> ```python theme={null}
> from harnest.mcp import ManagedMCPClient
>
> client: ManagedMCPClient
> result = await client.list_resource_templates()
> ```

### ManagedMCPClient.list\_prompts

```python theme={null}
async ManagedMCPClient.list_prompts(cursor: str | None = None) -> Any
```

List prompt descriptions and arguments without rendering messages.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `cursor` | `str \| None` | `None` |
>
> ```python theme={null}
> from harnest.mcp import ManagedMCPClient
>
> client: ManagedMCPClient
> result = await client.list_prompts()
> ```

### ManagedMCPClient.read\_resource

```python theme={null}
async ManagedMCPClient.read_resource(uri: str) -> Any
```

Read an allowed MCP URI through the same audit and permission boundary.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `uri` | `str` | Required |
>
> ```python theme={null}
> from harnest.mcp import ManagedMCPClient
>
> client: ManagedMCPClient
> result = await client.read_resource(uri=...)
> ```

### ManagedMCPClient.get\_prompt

```python theme={null}
async ManagedMCPClient.get_prompt(name: str, arguments: Mapping[str, str] | None = None) -> Any
```

Return prompt messages as data, never as higher-priority instructions.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `name` | `str` | Required |
> | `arguments` | `Mapping[str, str] \| None` | `None` |
>
> ```python theme={null}
> from harnest.mcp import ManagedMCPClient
>
> client: ManagedMCPClient
> result = await client.get_prompt(name=...)
> ```

### ManagedMCPClient.call\_tool

```python theme={null}
async ManagedMCPClient.call_tool(name: str, arguments: Mapping[str, Any] | None = None) -> Any
```

Dispatch one discovered tool through its governed shared path.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `name` | `str` | Required |
> | `arguments` | `Mapping[str, Any] \| None` | `None` |
>
> ```python theme={null}
> from harnest.mcp import ManagedMCPClient
>
> client: ManagedMCPClient
> result = await client.call_tool(name=...)
> ```


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