praval.mcp.client

Tools-only MCP client integration for Praval agents.

Classes

`MCPClient`(config)	Async tools-only MCP client with bounded execution and cleanup.
`MCPServerConfig`(**data)	Configuration for one stdio or Streamable HTTP MCP server.

Exceptions

`MCPClientClosedError`	Raised when an MCP operation is attempted after closure.
`MCPConnectionError`	Raised when an MCP connection cannot be established.
`MCPError`	Base error for Praval MCP client operations.
`MCPToolError`	Raised for invalid MCP tool discovery or registration state.

class praval.mcp.client.MCPClient(config)[source]

Bases: object

Async tools-only MCP client with bounded execution and cleanup.

Parameters:: config (MCPServerConfig)

__init__(config)[source]

Parameters:: config (MCPServerConfig)

property connected: bool: Return whether the MCP session is active.

async connect()[source]

Connect and initialize the configured MCP server exactly once.

Return type:: None

async close()[source]

Close the MCP session and any stdio process; safe to call twice.

Return type:: None

async list_tools()[source]

Discover MCP tools and convert their schemas to Praval ToolSpecs.

Return type:: List[ToolSpec]

async register_tools(agent)[source]

Discover tools and register async handlers on an Agent.

Return type:: List[ToolSpec]
Parameters:: agent (Any)

async call_tool(name, arguments)[source]

Execute a discovered MCP tool and normalize its supported content.

Return type:

ToolResult

Parameters:

name (str)
arguments (Dict[str, Any])

exception praval.mcp.client.MCPClientClosedError[source]

Bases: MCPError

Raised when an MCP operation is attempted after closure.

exception praval.mcp.client.MCPConnectionError[source]

Bases: MCPError

Raised when an MCP connection cannot be established.

exception praval.mcp.client.MCPError[source]

Bases: RuntimeError

Base error for Praval MCP client operations.

class praval.mcp.client.MCPServerConfig(**data)[source]

Bases: BaseModel

Configuration for one stdio or Streamable HTTP MCP server.

Parameters:

name (str)
transport (Literal['stdio', 'streamable_http'])
command (str | None)
args (List[str])
env (Dict[str, str] | None)
cwd (Path | None)
url (str | None)
headers (Dict[str, str])
connection_timeout (float)
tool_timeout (float)
tool_name_prefix (str | None)
require_approval (bool)
max_result_size (int)

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

transport: Literal['stdio', 'streamable_http']

command: str | None

args: List[str]

env: Dict[str, str] | None

cwd: Path | None

url: str | None

headers: Dict[str, str]

connection_timeout: float

tool_timeout: float

tool_name_prefix: str | None

require_approval: bool

max_result_size: int

validate_transport()[source]

Validate mutually exclusive transport settings and URL security.

Return type:: MCPServerConfig

property resolved_tool_name_prefix: str: Return the configured namespace prefix or the server-name default.

exception praval.mcp.client.MCPToolError[source]

Bases: MCPError

Raised for invalid MCP tool discovery or registration state.