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:

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_endpoint_url(): it must be https, on the standard port, and every address its host resolves to must be public. The one exception is the local environment, where a loopback host, e.g. http://localhost:9357, is permitted, so that a developer’s MCPClients can reach the platform’s own MCP server. 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 (dict[str, Any] | None) – 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.

A request to the staff-only endpoint of this platform’s own MCPServer also carries the signed acting user, the user who is chatting, from acting_user_headers(). No other server gets it.

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:
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 (list[str] | None) – 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.

smarter.apps.mcpclient.connection.validate_endpoint_url(url)[source]

Validate that Smarter may connect to an MCP server’s URL.

In the local environment, a loopback host, e.g. http://localhost:9357/ or https://127.0.0.1/, is permitted, on any port, so that a developer’s MCPClients can reach MCP servers that run on their machine, such as the platform’s own. Every other URL, and every URL in every other environment, must pass validate_public_url(). Loopback hosts are never permitted in a deployed environment, where they would let an MCPClient reach the services of the Smarter server itself.

Parameters:

url (str) – The URL.

Raises:

SafeHttpError – If the URL is not permitted.

Return type:

None