cayu.mcp.base

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.

McpClient

from cayu.mcp import McpClient

Factory for initialized MCP sessions.

Bases: ABC.

connect (method)

async McpClient.connect(server: McpServerSpec) -> McpSession

Connect to one MCP server.

Release source · Runtime guarantees · Capability guides

McpInitializeResult

from cayu.mcp import McpInitializeResult

Validated server metadata established for an MCP connection.

Bases: BaseModel.

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
protocol_version	str	required
server_name	str | None	None
server_version	str | None	None
instructions	str | None	None
capabilities	dict[str, Any]	Field(default_factory=dict)

validate_protocol_version (method)

McpInitializeResult.validate_protocol_version(value: str, info) -> str

validate_optional_strings (method)

McpInitializeResult.validate_optional_strings(value: str | None, info) -> str | None

copy_capabilities (method)

McpInitializeResult.copy_capabilities(value)

Release source · Runtime guarantees · Capability guides

McpResourceDefinition

from cayu.mcp import McpResourceDefinition

Resource definition advertised by an MCP server.

Bases: BaseModel.

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
uri	str	required
name	str | None	None
description	str | None	None
mime_type	str | None	None
metadata	dict[str, Any]	Field(default_factory=dict)

validate_uri (method)

McpResourceDefinition.validate_uri(value: str, info) -> str

validate_optional_strings (method)

McpResourceDefinition.validate_optional_strings(value: str | None, info) -> str | None

copy_metadata (method)

McpResourceDefinition.copy_metadata(value)

Release source · Runtime guarantees · Capability guides

McpResourceResult

from cayu.mcp import McpResourceResult

Result returned by an MCP resources/read request.

Bases: BaseModel.

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
contents	list[dict[str, Any]]	Field(default_factory=list)

copy_contents (method)

McpResourceResult.copy_contents(value)

Release source · Runtime guarantees · Capability guides

McpServerSpec

from cayu.mcp import McpServerSpec

Configuration for an external MCP server.

Bases: BaseModel.

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
name	str	required
connection_id	str | None	None
command	list[str] | None	None
url	str | None	None
env	dict[str, str]	Field(default_factory=dict)
secret_env	dict[str, SecretRef]	Field(default_factory=dict)
headers	dict[str, str]	Field(default_factory=dict)
secret_headers	dict[str, SecretRef]	Field(default_factory=dict)
metadata	dict[str, Any]	Field(default_factory=dict)

validate_secret_config_keys (method)

McpServerSpec.validate_secret_config_keys(value, info)

copy_secret_config_data (method)

McpServerSpec.copy_secret_config_data(value)

copy_json_config_data (method)

McpServerSpec.copy_json_config_data(value, info)

validate_nonblank_name (method)

McpServerSpec.validate_nonblank_name(value: str, info) -> str

validate_optional_nonblank_strings (method)

McpServerSpec.validate_optional_nonblank_strings(value: str | None, info) -> str | None

validate_command_items (method)

McpServerSpec.validate_command_items(value: list[str] | None) -> list[str] | None

validate_transport (method)

McpServerSpec.validate_transport() -> McpServerSpec

validate_secret_config_collisions (method)

McpServerSpec.validate_secret_config_collisions() -> McpServerSpec

Release source · Runtime guarantees · Capability guides

McpSession

from cayu.mcp import McpSession

Established connection to one MCP server.

Bases: ABC.

secret_redactor (property)

McpSession.secret_redactor() -> SecretRedactor

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

A hostile or buggy MCP server can echo injected secrets back through tool content, structured output, stderr, or protocol errors, so the toolset scrubs results with this before they reach model-visible context.

initialize_result (property)

McpSession.initialize_result() -> McpInitializeResult

Validated metadata established for this MCP connection.

list_tools (method)

async McpSession.list_tools() -> tuple[McpToolDefinition, ...]

Return tools advertised by the server.

call_tool (method)

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

Call one server tool.

list_resources (method)

async McpSession.list_resources() -> tuple[McpResourceDefinition, ...]

Return resources advertised by the server.

read_resource (method)

async McpSession.read_resource(uri: str) -> McpResourceResult

Read one server resource.

close (method)

async McpSession.close() -> None

Close the server connection.

Release source · Runtime guarantees · Capability guides

McpToolDefinition

from cayu.mcp import McpToolDefinition

Tool definition advertised by an MCP server.

Bases: BaseModel.

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
name	str	required
description	str	''
input_schema	dict[str, Any]	Field(default_factory=dict)
annotations	dict[str, Any]	Field(default_factory=dict)

validate_name (method)

McpToolDefinition.validate_name(value: str, info) -> str

validate_description (method)

McpToolDefinition.validate_description(value: str) -> str

copy_json_data (method)

McpToolDefinition.copy_json_data(value, info)

Release source · Runtime guarantees · Capability guides

McpToolResult

from cayu.mcp import McpToolResult

Result returned by an MCP tools/call request.

Bases: BaseModel.

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
content	list[dict[str, Any]]	Field(default_factory=list)
structured_content	Any	None
is_error	StrictBool	False

copy_json_data (method)

McpToolResult.copy_json_data(value, info)

Release source · Runtime guarantees · Capability guides