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’sMCPServerCatalog: 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_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:
objectWhat 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>)
- tools: list[MCPToolInfo]
- class smarter.apps.mcpclient.connection.MCPServerConnection(mcpclient)[source]
Bases:
objectA connection to an MCPClient’s MCP server.
- Parameters:
mcpclient (
MCPClient) – The MCPClient.
- call_tool(tool_name, arguments=None)[source]
Call one of the MCP server’s tools.
- Parameters:
- Return type:
- Returns:
The result, as text for the LLM. If the tool reports an error, the result’s
is_erroris True, and its text describes the error.- Raises:
SmarterMCPClientPermissionError – If
allowed_toolsdoes 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:
- 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_toolsallows them.- Return type:
- read_resource(uri)[source]
Read one of the MCP server’s resources.
- Parameters:
uri (
str) – The URI of the resource.- Return type:
- Returns:
The resource’s text content, for the LLM.
- Raises:
SmarterMCPClientPermissionError – If
allowed_resourcesdoes 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:
- run(operation, description)[source]
Connect to the MCP server, perform the handshake, run an operation, and disconnect.
- Parameters:
- 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.Clientconnects 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’smcp.client.Transportprotocol.- Parameters:
http_client (
AsyncClient) – The guarded httpx2 client, for the Streamable HTTP transport.- Returns:
A
streamable_http_client()orsse_client()context manager.- Return type:
Transport- Raises:
SmarterMCPClientConfigurationError – If the transport is not supported.
- class smarter.apps.mcpclient.connection.MCPToolInfo(name, description='', title=None, input_schema=<factory>, read_only=None, destructive=None)[source]
Bases:
objectA tool that an MCP server advertises.
- __init__(name, description='', title=None, input_schema=<factory>, read_only=None, destructive=None)
- class smarter.apps.mcpclient.connection.MCPToolResult(text, is_error=False)[source]
Bases:
objectThe result of a tool call, as text for the LLM.
- __init__(text, is_error=False)
- smarter.apps.mcpclient.connection.is_resource_allowed(mcpclient, uri)[source]
Return whether the LLM may read one of an MCPClient’s server’s resources.
- 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.
- smarter.apps.mcpclient.connection.matches_any(value, patterns)[source]
Return whether a value matches any of a list of glob patterns.
- 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.
- smarter.apps.mcpclient.connection.truncate(text, max_characters)[source]
Truncate text to at most
max_characters, marking the truncation.
- 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/orhttps://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 passvalidate_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: