cayu.mcp.tools

Public Cayu API. Definitions are grouped by their public source module, and definitions from private implementation modules appear on their package’s page; adding a symbol does not move existing links. The import shown at each entry is a supported public namespace. Read the Python API overview and install the required extra.

`connect_mcp_toolset`

from cayu.mcp import connect_mcp_toolset

Connect to one MCP server and return its initialized toolset.

async connect_mcp_toolset(server: McpServerSpec, *, client: McpClient | None=None) -> McpToolset

Release source · Runtime guarantees · Capability guides

`mcp_cayu_tool_name`

from cayu.mcp import mcp_cayu_tool_name

mcp_cayu_tool_name(server_name: str, tool_name: str) -> str

Release source · Runtime guarantees · Capability guides

`mcp_tool_manifest_hash`

from cayu.mcp import mcp_tool_manifest_hash

Return a stable hash of the MCP tool contract Cayu exposes.

mcp_tool_manifest_hash(*, server: McpServerSpec, initialize_result: McpInitializeResult, definitions: tuple[McpToolDefinition, ...]) -> str

Release source · Runtime guarantees · Capability guides

`mcp_tool_manifest_identity`

from cayu.mcp import mcp_tool_manifest_identity

Return an opaque candidate identity for one MCP server connection.

definitions remains accepted for source compatibility with the original helper, but manifest contents intentionally do not participate in identity. Only an explicit McpServerSpec.connection_id is authoritative for runtime manifest history. The server-name form exists solely so a rejected ID-less toolset can carry bounded, non-identifying audit evidence.

mcp_tool_manifest_identity(*, server: McpServerSpec, definitions: tuple[McpToolDefinition, ...] | None=None) -> str

Release source · Runtime guarantees · Capability guides

`mcp_tool_manifest_server_hash`

from cayu.mcp import mcp_tool_manifest_server_hash

Return a stable hash of MCP server metadata that affects the manifest.

mcp_tool_manifest_server_hash(*, server: McpServerSpec, initialize_result: McpInitializeResult) -> str

Release source · Runtime guarantees · Capability guides

`mcp_tool_manifest_tools`

from cayu.mcp import mcp_tool_manifest_tools

Return compact per-tool manifest entries for drift auditing.

mcp_tool_manifest_tools(*, server: McpServerSpec, definitions: tuple[McpToolDefinition, ...]) -> tuple[dict[str, Any], ...]

Release source · Runtime guarantees · Capability guides

`mcp_toolset_manifest_diff`

from cayu.mcp import mcp_toolset_manifest_diff

Compare two immutable snapshots of the same MCP source.

mcp_toolset_manifest_diff(previous: McpToolset, current: McpToolset) -> McpToolsetManifestDiff

Release source · Runtime guarantees · Capability guides

`McpToolAdapter`

from cayu.mcp import McpToolAdapter

Expose one MCP server tool as a Cayu tool.

Bases: Tool.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
`spec`	`ToolSpec`	`required`

init (method)

McpToolAdapter.__init__(*, toolset: McpToolset, definition: McpToolDefinition, name: str | None=None) -> None

name (property)

McpToolAdapter.name() -> str

execution_profile_identity (property)

McpToolAdapter.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Return the stable behavior declaration frozen with this tool’s spec.

retain_arguments_for_model (property)

McpToolAdapter.retain_arguments_for_model() -> bool

Retain bounded redacted original inputs privately for the same profile.

Independent of audit publication; oversized and compacted-away inputs may be omitted. This does not grant knowledge read or activation rights.

description (property)

McpToolAdapter.description() -> str

schema (property)

McpToolAdapter.schema() -> dict[str, Any]

run (method)

async McpToolAdapter.run(ctx: ToolContext, args: dict[str, Any]) -> ToolResult

toolset (property)

McpToolAdapter.toolset() -> McpToolset

mcp_manifest_hash (property)

McpToolAdapter.mcp_manifest_hash() -> str

server (property)

McpToolAdapter.server() -> McpServerSpec

definition (property)

McpToolAdapter.definition() -> McpToolDefinition

Release source · Runtime guarantees · Capability guides

`McpToolset`

from cayu.mcp import McpToolset

Persistent established MCP server connection plus Cayu tool adapters.

init (method)

McpToolset.__init__(*, server: McpServerSpec, session: McpSession, definitions: tuple[McpToolDefinition, ...]) -> None

server (property)

McpToolset.server() -> McpServerSpec

session (property)

McpToolset.session() -> McpSession

generation (property)

McpToolset.generation() -> int

Immutable source generation represented by this toolset snapshot.

definitions (property)

McpToolset.definitions() -> tuple[McpToolDefinition, ...]

tools (property)

McpToolset.tools() -> tuple[McpToolAdapter, ...]

refresh_state (property)

McpToolset.refresh_state() -> McpToolsetRefreshState

Return the source’s current dispatch state.

manifest_identity_is_explicit (property)

McpToolset.manifest_identity_is_explicit() -> bool

Whether the cached manifest identity came from an explicit connection ID.

manifest_identity (property)

McpToolset.manifest_identity() -> str

manifest_hash (property)

McpToolset.manifest_hash() -> str

manifest_server_hash (property)

McpToolset.manifest_server_hash() -> str

manifest_tools (property)

McpToolset.manifest_tools() -> tuple[dict[str, Any], ...]

connect (method)

async McpToolset.connect(server: McpServerSpec, *, client: McpClient | None=None) -> McpToolset

initialize_result (property)

McpToolset.initialize_result() -> McpInitializeResult

secret_redactor (property)

McpToolset.secret_redactor() -> SecretRedactor

Redactor for secrets injected into this server’s session (empty if none).

process_capability_evidence (property)

McpToolset.process_capability_evidence()

Configured process-lifecycle evidence for stdio-backed toolsets.

call_tool (method)

async McpToolset.call_tool(name: str, arguments: dict[str, Any]) -> McpToolResult

close (method)

async McpToolset.close() -> None

Release source · Runtime guarantees · Capability guides

`McpToolsetManifestDiff`

from cayu.mcp import McpToolsetManifestDiff

Bounded application-visible difference between two MCP snapshots.

Decorators: @dataclass(frozen=True, slots=True).

Fields and attributes

Name	Type	Default
`server_changed`	`bool`	`required`
`added_tools`	`tuple[str, ...]`	`()`
`removed_tools`	`tuple[str, ...]`	`()`
`changed_tools`	`tuple[str, ...]`	`()`

changed (property)

McpToolsetManifestDiff.changed() -> bool

policy_input (method)

McpToolsetManifestDiff.policy_input() -> dict[str, Any]

Return a detached value accepted by McpManifestPolicy.

Release source · Runtime guarantees · Capability guides

`McpToolsetRefreshBlocked`

from cayu.mcp import McpToolsetRefreshBlocked

Raised when application policy rejects a refreshed MCP manifest.

Bases: RuntimeError.

This type’s implementation and inherited behavior are available in the linked release source.

Release source · Runtime guarantees · Capability guides

`McpToolsetRefreshResult`

from cayu.mcp import McpToolsetRefreshResult

Accepted result of one trigger-independent MCP catalogue refresh.

Decorators: @dataclass(frozen=True, slots=True).

Fields and attributes

Name	Type	Default
`toolset`	`McpToolset`	`required`
`status`	`str`	`required`
`previous_generation`	`int`	`required`
`generation`	`int`	`required`
`previous_manifest_hash`	`str`	`required`
`manifest_hash`	`str`	`required`
`diff`	`McpToolsetManifestDiff`	`required`
`policy_action`	`str \| None`	`None`

Release source · Runtime guarantees · Capability guides

`McpToolsetRefreshState`

from cayu.mcp import McpToolsetRefreshState

Live dispatch state for one refreshable MCP source.

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`READY`	`class attribute`	`'ready'`
`DIRTY`	`class attribute`	`'dirty'`
`REFRESHING`	`class attribute`	`'refreshing'`
`QUARANTINED`	`class attribute`	`'quarantined'`
`CLOSED`	`class attribute`	`'closed'`

Release source · Runtime guarantees · Capability guides

`McpToolsetUnavailable`

from cayu.mcp import McpToolsetUnavailable

Raised when an MCP snapshot no longer has live dispatch authority.

Bases: McpProtocolError.

This type’s implementation and inherited behavior are available in the linked release source.

Release source · Runtime guarantees · Capability guides