Struct McpConnection 

pub struct McpConnection { /* private fields */ }

A live connection to a single MCP server, wrapping an rmcp::service::RunningService.

Implementations

impl McpConnection

pub async fn connect(config: &McpServerConfig) -> Result<Self, McpError>

Connects to an MCP server, performs the rmcp initialize handshake, and returns a ready-to-use connection. No sampling / elicitation / roots responders are wired; use Self::connect_with_handler when the server may issue those requests.

pub async fn connect_with_handler( config: &McpServerConfig, handler_config: McpHandlerConfig, ) -> Result<Self, McpError>

Connects to an MCP server with a fully configured McpHandlerConfig.

pub fn from_running_service( server_id: impl Into<McpServerId>, service: RunningService<RoleClient, McpClientHandler>, notifications: UnboundedReceiver<McpServerNotification>, ) -> Self

Adopts an externally constructed rmcp::service::RunningService as an McpConnection.

Use this when you need a transport rmcp supports but McpTransportBinding does not (in-memory pipes for tests, websockets, custom IO). Pair the service with the notification receiver returned by McpHandlerConfig::build so list-change notifications stay observable.

The connection has no McpServerConfig attached, so reconnect-on-auth is unavailable; resolve_auth only updates stored credentials in this mode. Server-pushed events from the underlying handler are not forwarded to subscribers — use Self::from_running_service_with_events paired with the broadcast sender from McpClientChannels when you need event delivery.

pub fn from_running_service_with_events( server_id: impl Into<McpServerId>, service: RunningService<RoleClient, McpClientHandler>, notifications: UnboundedReceiver<McpServerNotification>, events: Sender<McpServerEvent>, ) -> Self

Variant of Self::from_running_service that wires the broadcast sender returned by McpHandlerConfig::build (or build_with) so Self::subscribe_events receivers observe the same stream the handler is publishing into.

pub fn from_running_service_with_events_and_handler_config( server_id: impl Into<McpServerId>, service: RunningService<RoleClient, McpClientHandler>, notifications: UnboundedReceiver<McpServerNotification>, events: Sender<McpServerEvent>, handler_config: McpHandlerConfig, ) -> Self

Variant of Self::from_running_service_with_events that also preserves the handler config used to build the adopted service.

Use this when the connection needs to reach client-side hooks that are not carried by the rmcp handler itself, such as McpAuthResponder and McpErrorResponder during McpToolAdapter invocation.

pub fn server_id(&self) -> &McpServerId

Returns the McpServerId for this connection.

pub fn capabilities(&self) -> &McpServerCapabilities

Returns the capabilities advertised by the server during initialize.

pub fn handler_config(&self) -> &McpHandlerConfig

Returns the McpHandlerConfig this connection was built with. Used by McpToolAdapter to reach the registered McpAuthResponder when an auth challenge surfaces.

pub fn subscribe_events(&self) -> Receiver<McpServerEvent>

Subscribes to the per-connection McpServerEvent broadcast.

Receivers buffer up to events_capacity (configured via McpHandlerConfig::with_events_capacity, defaults to DEFAULT_EVENTS_CAPACITY) before slow consumers are signalled with broadcast::error::RecvError::Lagged. Catalog *ListChanged events are also delivered through the legacy McpServerNotification receiver consumed by McpServerManager::refresh_changed_catalogs.

pub async fn subscribe_resource( &self, uri: impl Into<String>, ) -> Result<(), McpError>

Subscribes to notifications/resources/updated for the given URI.

Updates surface as McpServerEvent::ResourceUpdated on every receiver returned by Self::subscribe_events.

pub async fn unsubscribe_resource( &self, uri: impl Into<String>, ) -> Result<(), McpError>

Cancels a previous Self::subscribe_resource subscription.

pub async fn set_logging_level( &self, level: McpLoggingLevel, ) -> Result<(), McpError>

Negotiates the minimum severity the server should emit through notifications/message. Surfaced as McpServerEvent::Logging.

pub async fn notify_cancelled( &self, params: McpCancelledNotificationParam, ) -> Result<(), McpError>

Sends a notifications/cancelled to the server, asking it to stop processing a previously issued request.

pub async fn notify_roots_list_changed(&self) -> Result<(), McpError>

Notifies the server that the client’s roots list has changed; servers may respond by re-issuing roots/list.

pub async fn close(&self) -> Result<(), McpError>

Gracefully closes the underlying rmcp service.

For Streamable HTTP this drives the rmcp transport to issue a DELETE against the negotiated session, releasing server-side state.

pub async fn resolve_auth( &self, resolution: AuthResolution, ) -> Result<(), McpError>

Stores or clears authentication credentials and, when configured to do so via McpServerConfig, reconnects to apply them.

pub async fn discover(&self) -> Result<McpDiscoverySnapshot, McpError>

Discovers tools, resources, and prompts that the server advertised.

pub async fn list_tools(&self) -> Result<Vec<McpTool>, McpError>

Lists all tools advertised by the connected MCP server.

pub async fn list_resources(&self) -> Result<Vec<McpResource>, McpError>

Lists all resources advertised by the connected MCP server.

pub async fn list_prompts(&self) -> Result<Vec<McpPrompt>, McpError>

Lists all prompts advertised by the connected MCP server.

pub async fn call_tool( &self, name: &str, arguments: Value, ) -> Result<CallToolResult, McpError>

Invokes a tool on the MCP server.

Returns the typed CallToolResult — the Vec<Content> block list, the optional structured_content field, and the is_error flag are all preserved. Adapters convert this into agentkit ToolOutput/[InvocableOutput] at the boundary.

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

Reads a resource from the MCP server by URI.

Returns the typed ReadResourceResult — the full Vec<McpResourceContents> is preserved (text vs blob, mime types, metadata). Use McpResourceHandle for the agentkit ResourceProvider view that collapses to a single inline DataRef.

pub async fn get_prompt( &self, name: &str, arguments: Value, ) -> Result<GetPromptResult, McpError>

Retrieves a prompt from the MCP server, rendering it with the given arguments.

Returns the typed GetPromptResult — message role and content blocks (text/image/audio/embedded resource) are preserved. Use McpPromptHandle for the collapsed agentkit PromptProvider view.