Struct Connection 

pub struct Connection { /* private fields */ }

An active connection to an MCP server using the Streamable HTTP transport.

Cheaply clonable (one Arc bump). When the last clone is dropped, the inner Arc ref count hits zero, the _listener_cancel_guard field is dropped, and the SSE listener task is cancelled — exiting any in-flight lines.next_line(), reconnect send(), or backoff sleep immediately without retrying against the now-dead proxy session.

Use the public methods (list_tools, call_tool, list_resources, read_resource, call_tool_as_message, tool_key) for the upstream MCP protocol surface. The inner state (ConnectionInner) is also reachable via Deref for read-only field access (e.g. connection.url, connection.initialize_result.server_info.name), but its methods are private — you must go through Connection.

Implementations

impl Connection

pub async fn delete(&self) -> Result<(), Error>

Tear this connection down explicitly.

1. Cancels the long-lived list-changed listener task immediately (drops the DropGuard in ConnectionInner::_listener_cancel_guard), so by the time the HTTP DELETE goes out the listener isn’t still holding an SSE read open against the upstream we’re about to close.
2. Issues DELETE / to the upstream with this connection’s Mcp-Session-Id and the same merged header set every other RPC stamps. Reuses ConnectionInner::call_timeout.
3. Treats 404 / 401 / 403 as success — the upstream is unreachable from these credentials anyway, which is the desired terminal state. Other non-2xx surfaces as super::Error::BadStatus.

Takes &self: the listener cancel is in-place, and dropping the surrounding Arc<ConnectionInner> (which closes the rest of the connection’s owned state) is the caller’s responsibility — usually by dropping the Arc<Session> holding it. Stateless callers that don’t hold a Connection should use Client::delete instead.

In-flight RPC ordering. This method does not block on in-flight call_tool / read_resource / list_tools / list_resources calls on the same connection. If one is outstanding when delete lands, the upstream may see DELETE before the RPC’s reply makes it back; the in-flight call then surfaces as a closed-connection error to whoever started it. That’s the spec-correct order (client said terminate) — drain on the caller side first if you need different semantics.

pub fn tool_key(&self) -> String

Returns a key identifying this connection for tool namespacing.

pub fn session_id(&self) -> &str

Returns the session ID for this connection.

pub async fn list_tools(&self) -> Result<Arc<Vec<Tool>>, Arc<Error>>

Returns all tools from the upstream server.

pub async fn call_tool( &self, params: &CallToolRequestParams, ) -> Result<CallToolResult, Error>

Calls a tool on the upstream server.

pub async fn call_tool_as_message( &self, params: &CallToolRequestParams, tool_call_id: String, ) -> Result<ToolMessage, Error>

Calls a tool and converts the result into a [ToolMessage].

pub async fn list_resources(&self) -> Result<Arc<Vec<Resource>>, Arc<Error>>

Returns all resources from the upstream server.

pub async fn read_resource( &self, uri: &str, ) -> Result<ReadResourceResult, Error>

Reads a resource from the upstream server.

pub fn set_on_tools_list_changed<F>(&self, callback: F)

where F: Fn() + Send + Sync + 'static,

Register a callback to fire whenever the upstream emits notifications/tools/list_changed.

Timing: the callback runs after the tool cache’s write lock is acquired but before the network paginate that replaces it. That means readers blocked on the read lock won’t return until the new list is in place, and the callback observes the moment the staleness window opens. The proxy uses this to emit its own notifications/tools/list_changed to downstream clients at the right instant.

Replaces any previously-registered tools-list-changed callback. All clones of this Connection share the same callback slot.

pub fn set_on_resources_list_changed<F>(&self, callback: F)

where F: Fn() + Send + Sync + 'static,

Register a callback to fire whenever the upstream emits notifications/resources/list_changed. Same timing contract as Connection::set_on_tools_list_changed.

Replaces any previously-registered resources-list-changed callback. All clones of this Connection share the same callback slot.

pub async fn set_extra_headers(&self, extras: IndexMap<String, String>)

Atomically replace the connection’s ConnectionInner::extra_headers bag. Every subsequent outbound HTTP request from this connection stamps the new map AFTER headers, with HeaderMap::insert REPLACE semantics — keys in extras override the same key in the per-URL headers bag set at Client::connect. Caller supplies the FULL replacement map; missing keys are dropped (no merge).

Used by the proxy to inject session-global headers (X-OBJECTIVEAI-RESPONSE-ID, X-OBJECTIVEAI-RESPONSE-IDS) that re-set on every inbound initialize, without re-dialing the upstream.

Trait Implementations

impl Clone for Connection

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Connection

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for Connection

type Target = ConnectionInner

The resulting type after dereferencing.

fn deref(&self) -> &ConnectionInner

Dereferences the value.