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, [ConnectionInner::Drop] runs, the listener-cancel DropGuard 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 subscribe_tools( &self, current: &[Tool], timeout: Duration, ) -> Result<Arc<Vec<Tool>>, Arc<Error>>

Returns the cached tool list as soon as it differs from current, or waits up to timeout for the next notifications/tools/list_changed from the upstream server before re-reading.

Wakes the moment a refresh writer takes the cache write lock, so the post-wake read is guaranteed to observe the new list rather than racing against the install. Safe to call from any number of tasks concurrently.

pub async fn subscribe_resources( &self, current: &[Resource], timeout: Duration, ) -> Result<Arc<Vec<Resource>>, Arc<Error>>

Resource counterpart of Connection::subscribe_tools.

pub async fn drain_notifications(&self) -> Result<Vec<ContentBlock>, Error>

Atomically drain the proxy’s pending_notifications queue for this session via GET /notify and return the queued content blocks. A second call returns [] until the next out-of-band POST /notify.

Intended for use at the start of an agent turn so notifications queued between turns — when the prior turn ended without a tool call, or the user is starting a fresh continuation — surface as a user message instead of being lost. The proxy’s existing tools/call response path still drains in-flight notifications arriving during a turn; this method covers the gap between turns.

A 404 from the proxy (session unknown — possible after a proxy restart) is mapped to an empty Vec so callers do not need to distinguish “no notifications” from “lost session” at the use site; the next upstream call will surface the lost-session condition through its own error path.

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

Non-draining peek at the proxy’s pending_notifications queue via GET /notify/queued. Returns true iff the queue holds at least one block. Companion to Connection::drain_notifications for callers that want to know whether queued blocks exist without consuming them.

A 404 from the proxy (session unknown — possible after a proxy restart) is mapped to Ok(false) for the same reason as the drain path: callers do not need to distinguish “no notifications” from “lost session” at the use site.

pub async fn enqueue_notifications( &self, blocks: &[ContentBlock], ) -> Result<(), Error>

POST <self.url>/notify against the ObjectiveAI MCP proxy. Appends blocks to the proxy’s pending-notifications queue for this session; they surface as a user message on the next tools/call response (wrapped in a <system-reminder> block) or as the head of the next agent turn when drained between turns.

Mirror of Connection::drain_notifications / Connection::has_pending_notifications for the inbound side. A 404 from the proxy means the session is gone — surfaced as SessionExpired so callers can distinguish “session lost” from “delivery failed” at the use site.

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.