MCP Server Connections

Connections to remote MCP servers.

MCPServerConnection connects an MCPClient to its MCP server with the official MCP Python SDK, and exposes three synchronous operations, each of which opens a connection, performs the MCP handshake, and closes the connection:

MCPServerConnection.discover() returns the server’s MCPServerCatalog: its protocol version, identity, instructions, capabilities and tools.
MCPServerConnection.call_tool() calls one of the server’s tools.
MCPServerConnection.read_resource() reads one of the server’s resources.

Security. The endpoint is user supplied, and the connection is made from the Smarter server, so every HTTP request, including redirects and the message endpoint of the legacy SSE transport, is checked with validate_public_url(): it must be https, on the standard port, and every address its host resolves to must be public. Credentials are read from the MCPClient’s Smarter Secret when a connection is made, and are sent only as HTTP headers. The stdio transport, which would run a command on the Smarter server, is not supported.

Note

Experimental. The MCPClient was designed and coded by Claude Code (Anthropic’s Claude Opus 5.5), with Lawrence McDaniel as co-author. It is experimental, and will be documented.

class smarter.apps.mcpclient.connection.MCPServerCatalog(protocol_version=None, server_name=None, server_version=None, instructions=None, has_tools=False, has_resources=False, tools=<factory>)[source]

Bases: object

What an MCP server reported during the handshake and tools/list.

__init__(protocol_version=None, server_name=None, server_version=None, instructions=None, has_tools=False, has_resources=False, tools=<factory>)

classmethod from_dict(data)[source]

Return a catalog from to_dict().

Return type:: MCPServerCatalog

has_resources: bool = False

has_tools: bool = False

instructions: str | None = None

protocol_version: str | None = None

server_name: str | None = None

server_version: str | None = None

to_dict()[source]

Return the catalog as a JSON-serializable dict, e.g. for caching.

Return type:: dict[str, Any]

tools: list[MCPToolInfo]

class smarter.apps.mcpclient.connection.MCPServerConnection(mcpclient)[source]

Bases: object

A connection to an MCPClient’s MCP server.

Parameters:: mcpclient (MCPClient) – The MCPClient.

__init__(mcpclient)[source]

call_tool(tool_name, arguments=None)[source]

Call one of the MCP server’s tools.

Parameters:

tool_name (str) – The name of the tool, as the server reports it.
arguments (Optional[dict[str, Any]]) – The tool’s arguments.

Return type:

MCPToolResult

Returns:

The result, as text for the LLM. If the tool reports an error, the result’s is_error is True, and its text describes the error.

Raises:

SmarterMCPClientPermissionError – If allowed_tools does not allow the tool.

credential()[source]

Return the MCPClient’s credential, from its Smarter Secret.

Raises:: SmarterMCPClientConfigurationError – If the Secret is missing or empty.
Return type:: str

discover()[source]

Return the MCP server’s catalog: its identity, instructions, capabilities and tools.

All of the server’s tools are returned, whether or not allowed_tools allows them.

Return type:: MCPServerCatalog

property formatted_class_name: str: The class name, for logging.

read_resource(uri)[source]

Read one of the MCP server’s resources.

Parameters:: uri (str) – The URI of the resource.
Return type:: str
Returns:: The resource’s text content, for the LLM.
Raises:: SmarterMCPClientPermissionError – If allowed_resources does not allow the URI.

request_headers()[source]

Return the HTTP headers to send to the MCP server: its custom headers, and its credential.

Raises:: SmarterMCPClientConfigurationError – If the credential is missing.
Return type:: dict[str, str]

run(operation, description)[source]

Connect to the MCP server, perform the handshake, run an operation, and disconnect.

Parameters:

operation (Callable[[Client], Awaitable[TypeVar(T)]]) – An async function of the connected mcp.Client.
description (str) – What the operation does, for error messages.

Return type:

TypeVar(T)

Returns:

The operation’s result.

Raises:

SmarterMCPClientConnectionError – If the server cannot be reached, fails the handshake, returns an error, or does not respond within the timeout.
SmarterMCPClientConfigurationError – If the MCPClient is misconfigured.

server_target(http_client)[source]

Return what the MCP SDK’s mcp.Client connects to: the MCPClient’s transport.

Both transports are async context managers that yield the SDK’s TransportStreams, a (read stream, write stream) pair, which is the SDK’s mcp.client.Transport protocol.

Parameters:: http_client (AsyncClient) – The guarded httpx2 client, for the Streamable HTTP transport.
Returns:: A streamable_http_client() or sse_client() context manager.
Return type:: Transport
Raises:: SmarterMCPClientConfigurationError – If the transport is not supported.

property timeout: float: Seconds to wait for the MCP server to connect and respond.

class smarter.apps.mcpclient.connection.MCPToolInfo(name, description='', title=None, input_schema=<factory>, read_only=None, destructive=None)[source]

Bases: object

A tool that an MCP server advertises.

__init__(name, description='', title=None, input_schema=<factory>, read_only=None, destructive=None)

description: str = ''

destructive: bool | None = None

input_schema: dict[str, Any]

name: str

read_only: bool | None = None

title: str | None = None

class smarter.apps.mcpclient.connection.MCPToolResult(text, is_error=False)[source]

Bases: object

The result of a tool call, as text for the LLM.

__init__(text, is_error=False)

is_error: bool = False

text: str

smarter.apps.mcpclient.connection.is_resource_allowed(mcpclient, uri)[source]

Return whether the LLM may read one of an MCPClient’s server’s resources.

Parameters:

mcpclient (MCPClient) – The MCPClient.
uri (str) – The URI of the resource.

Return type:

bool

Returns:

True if the URI matches one of the allowed_resources patterns. If there are none, no resource may be read.

smarter.apps.mcpclient.connection.is_tool_allowed(mcpclient, tool_name)[source]

Return whether an MCPClient offers one of its server’s tools to the LLM.

Parameters:

mcpclient (MCPClient) – The MCPClient.
tool_name (str) – The name of the tool, as the server reports it.

Return type:

bool

Returns:

True if allowed_tools is empty, or the name matches one of its patterns.

smarter.apps.mcpclient.connection.matches_any(value, patterns)[source]

Return whether a value matches any of a list of glob patterns.

Parameters:

value (str) – The value, e.g. a tool name or a resource URI.
patterns (Optional[list[str]]) – Glob patterns, e.g. search_*.

Return type:

bool

Returns:

True if the value matches a pattern.

smarter.apps.mcpclient.connection.run_sync(fn)[source]

Run a coroutine function to completion, from synchronous code.

The prompt pipeline, the Celery tasks and the views are synchronous. If this thread already runs an event loop, the coroutine is run in a new event loop in another thread.

Parameters:: fn (Callable[[], Awaitable[TypeVar(T)]]) – A function that returns the coroutine to run.
Return type:: TypeVar(T)
Returns:: The coroutine’s result.

smarter.apps.mcpclient.connection.truncate(text, max_characters)[source]

Truncate text to at most max_characters, marking the truncation.

Parameters:

text (str) – The text.
max_characters (int) – The maximum length.

Return type:

str

Returns:

The text, truncated if necessary.