Class MCPConnection

A ready connection to an MCP server.

The connection has the same public API for legacy, sessionful MCP servers and modern, sessionless MCP servers. The underlying SDK owns the lifecycle distinction and protocol negotiation.

Sessions handle:

Connection lifecycle (connect, disconnect, initialize)
Tool invocation
Resource access
Prompt retrieval
Notification handling
Root directory management

Sessions are typically created by MCPClient.createSession() rather than being instantiated directly.

Example

// Create via client
const client = new MCPClient('./config.json');
const session = await client.createSession('my-server');

// Use the session
const tools = await session.listTools();
const result = await session.callTool('my-tool', { arg: 'value' });

Example

// Manual creation (advanced)
import { StdioConnector } from "@mcp-use/client";

const connector = new StdioConnector({
  command: 'node',
  args: ['server.js']
});
const session = new MCPSession(connector);
await session.initialize();

See

BaseConnector for connector implementations

Index

Constructors

constructor

new MCPConnection(
connector: BaseConnector,
autoConnect?: boolean,
): MCPConnection
Creates a new MCP session.
Parameters
- connector: BaseConnector
  The connector to use for communication (Stdio, HTTP, WebSocket)
- autoConnect: boolean = true
  Whether to automatically connect during initialization (default: true)
Returns MCPConnection
Example
```
const connector = new HttpConnector({ url: 'http://localhost:3000/mcp' });
const session = new MCPSession(connector);
await session.initialize(); // Auto-connects and initializes
```
Example
```
// Manual connection control
const session = new MCPSession(connector, false);
await session.connect();
await session.initialize();
```
- Defined in core/session.ts:142

Properties

`Readonly`connector

connector: BaseConnector

The underlying connector managing the transport layer. This is the Stdio, HTTP, or WebSocket connector handling actual communication.

Accessors

info

get info(): MCPConnectionInfo
Normalized server metadata for this ready connection.

Returns MCPConnectionInfo

Throws
When called before protocol negotiation completes.
- Defined in core/session.ts:367

isConnected

get isConnected(): boolean
Checks if the session is currently connected to the server.

Returns boolean
True if connected, false otherwise
Example
```
if (session.isConnected) {
  const tools = await session.listTools();
}
```
- Defined in core/session.ts:230

negotiatedProtocolVersion

get negotiatedProtocolVersion(): string | undefined
The negotiated protocol version string for this session's connection.

Returns string | undefined
- Defined in core/session.ts:358

protocolEra

get protocolEra(): ProtocolEra | undefined
The negotiated protocol era for this session's connection: "legacy" (2025-era) or "modern" (2026-07-28-era). undefined before the connection has negotiated.

Returns ProtocolEra | undefined
- Defined in core/session.ts:353

serverCapabilities

get serverCapabilities(): Record<string, unknown>
Get the server capabilities advertised during initialization.

Returns Record<string, unknown>
Server capabilities object
- Defined in core/session.ts:335

serverInfo

get serverInfo(): MCPServerInfo | null
Get the server information (name and version).

Returns MCPServerInfo | null
Server info object or null if not available
- Defined in core/session.ts:344

tools

get tools(): {}[]
Get the cached list of tools from the server.

Returns {}[]
Array of available tools
Example
```
const tools = session.tools;
console.log(`Available tools: ${tools.map(t => t.name).join(", ")}`);
```
- Defined in core/session.ts:309

Methods

callTool

callTool(
    name: string,
    args?: Record<string, any>,
    options?: RequestOptions,
): Promise<{ [key: string]: unknown }>
Call a tool on the server.
Parameters
- name: string
  Name of the tool to call
- args: Record<string, any> = {}
  Arguments to pass to the tool (defaults to empty object)
- Optionaloptions: RequestOptions
  Optional request options (timeout, progress handlers, etc.)
Returns Promise<{ [key: string]: unknown }>
Result from the tool execution
Example
```
const result = await session.callTool("add", { a: 5, b: 3 });
console.log(`Result: ${result.content[0].text}`);
```
- Defined in core/session.ts:418

complete

complete(
params: {},
options?: RequestOptions,
): Promise<{ [key: string]: unknown }>
Request completion suggestions for a prompt or resource template argument.
Parameters
- params: {}
  Completion request parameters
- Optionaloptions: RequestOptions
  Request options
Returns Promise<{ [key: string]: unknown }>
Completion suggestions from the server
Example
```
// Complete a prompt argument
const result = await session.complete({
  ref: { type: "ref/prompt", name: "my-prompt" },
  argument: { name: "language", value: "py" }
});
console.log(result.completion.values); // ["python"]
```
- Defined in core/session.ts:492

connect

connect(): Promise<void>
Establishes the connection to the MCP server.

This method starts the underlying transport (spawns process for Stdio, opens WebSocket, etc.) but does not perform the MCP initialization handshake. Call initialize after connecting.

Returns Promise<void>
Promise that resolves when connected
Example
```
await session.connect();
await session.initialize();
```
See
- initialize for performing the MCP handshake
- disconnect for closing the connection
- Defined in core/session.ts:165

disconnect

disconnect(): Promise<void>
Closes the connection to the MCP server.

This method gracefully shuts down the transport and cleans up resources. After disconnecting, the session cannot be used until reconnected.

Returns Promise<void>
Promise that resolves when disconnected
Example
```
await session.disconnect();
console.log('Session closed');
```
See
connect for establishing connections
- Defined in core/session.ts:185

getPrompt

getPrompt(
name: string,
args: Record<string, any>,
): Promise<{ [key: string]: unknown }>
Get a specific prompt with arguments.
Parameters
- name: string
  Name of the prompt to get
- args: Record<string, any>
  Arguments for the prompt
Returns Promise<{ [key: string]: unknown }>
Prompt result
Example
```
const prompt = await session.getPrompt("greeting", { name: "Alice" });
console.log(prompt.messages);
```
- Defined in core/session.ts:575

getRoots

getRoots(): {}[]
Gets the current roots advertised to the server.

Roots represent directories or files that the client has provided access to. The server may use this information to scope its operations.

Returns {}[]
Array of Root objects
Example
```
const roots = session.getRoots();
console.log(`Current roots: ${roots.map(r => r.uri).join(', ')}`);
```
See
setRoots for updating roots
- Defined in core/session.ts:294

initialize

initialize(): Promise<void>
Initializes the MCP session with the server.

This method performs the MCP initialization handshake, exchanging capabilities and metadata with the server. If autoConnect is true and the session is not yet connected, it will connect first.

After initialization, you can list and call tools, read resources, etc.

Returns Promise<void>
Promise that resolves when initialized
Example
```
const session = await client.createSession('my-server', false);
await session.connect();
await session.initialize();
// Now ready to use
const tools = await session.listTools();
```
See
connect for establishing the connection first
- Defined in core/session.ts:211

listAllResources

listAllResources(options?: RequestOptions): Promise<{ resources: any[] }>
List all resources from the server, automatically handling pagination.
Parameters
- Optionaloptions: RequestOptions
  Request options
Returns Promise<{ resources: any[] }>
Complete list of all resources
Example
```
const result = await session.listAllResources();
console.log(`Total resources: ${result.resources.length}`);
```
- Defined in core/session.ts:455

listPrompts

listPrompts(): Promise<{ [key: string]: unknown }>
List available prompts from the server.

Returns Promise<{ [key: string]: unknown }>
List of available prompts
Example
```
const result = await session.listPrompts();
console.log(`Available prompts: ${result.prompts.length}`);
```
- Defined in core/session.ts:558

listResources

listResources(
cursor?: string,
options?: RequestOptions,
): Promise<{ [key: string]: unknown }>
List resources from the server with optional pagination.
Parameters
- Optionalcursor: string
  Optional cursor for pagination
- Optionaloptions: RequestOptions
  Request options
Returns Promise<{ [key: string]: unknown }>
Resource list with optional nextCursor for pagination
Example
```
const result = await session.listResources();
console.log(`Found ${result.resources.length} resources`);
```
- Defined in core/session.ts:439

listResourceTemplates

listResourceTemplates(
options?: RequestOptions,
): Promise<{ [key: string]: unknown }>
List resource templates from the server.
Parameters
- Optionaloptions: RequestOptions
  Request options
Returns Promise<{ [key: string]: unknown }>
List of available resource templates
Example
```
const result = await session.listResourceTemplates();
console.log(`Available templates: ${result.resourceTemplates.length}`);
```
- Defined in core/session.ts:471

listTools

listTools(options?: RequestOptions): Promise<{}[]>
List all available tools from the MCP server. This method fetches fresh tools from the server, unlike the tools getter which returns cached tools.
Parameters
- Optionaloptions: RequestOptions
  Optional request options
Returns Promise<{}[]>
Array of available tools
Example
```
const tools = await session.listTools();
console.log(`Available tools: ${tools.map(t => t.name).join(", ")}`);
```
- Defined in core/session.ts:326

on

on(event: "notification", handler: NotificationHandler): void
Register an event handler for session events
Parameters
- event: "notification"
  The event type to listen for
- handler: NotificationHandler
  The handler function to call when the event occurs
Returns void
Example
```
session.on("notification", async (notification) => {
  console.log(`Received: ${notification.method}`, notification.params);

  if (notification.method === "notifications/tools/list_changed") {
    // Refresh tools list
  }
});
```
- Defined in core/session.ts:251

readResource

readResource(
uri: string,
options?: RequestOptions,
): Promise<{ [key: string]: unknown }>
Read a resource by URI.
Parameters
- uri: string
  URI of the resource to read
- Optionaloptions: RequestOptions
  Request options
Returns Promise<{ [key: string]: unknown }>
Resource content
Example
```
const resource = await session.readResource("file:///path/to/file.txt");
console.log(resource.contents);
```
- Defined in core/session.ts:512

request

request(
    method: string,
    params?: Record<string, any> | null,
    options?: RequestOptions,
): Promise<unknown>
Send a raw request through the client.
Parameters
- method: string
  MCP method name
- params: Record<string, any> | null = null
  Request parameters
- Optionaloptions: RequestOptions
  Request options
Returns Promise<unknown>
Response from the server
Example
```
const result = await session.request("custom/method", { key: "value" });
```
- Defined in core/session.ts:592

setRoots

setRoots(roots: {}[]): Promise<void>
Set roots and notify the server. Roots represent directories or files that the client has access to.
Parameters
- roots: {}[]
  Array of Root objects with uri (must start with "file://") and optional name
Returns Promise<void>
Deprecated
Roots are a v1 compatibility feature and are not part of the sessionless v2 protocol.
Example
```
await session.setRoots([
  { uri: "file:///home/user/project", name: "My Project" },
  { uri: "file:///home/user/data" }
]);
```
- Defined in core/session.ts:274

subscribeToResource

subscribeToResource(uri: string, options?: RequestOptions): Promise<{}>
Subscribe to resource updates.
Parameters
- uri: string
  URI of the resource to subscribe to
- Optionaloptions: RequestOptions
  Request options
Returns Promise<{}>
Example
```
await session.subscribeToResource("file:///path/to/file.txt");
// Now you'll receive notifications when this resource changes
```
- Defined in core/session.ts:528

supports

supports(capability: string): boolean
Whether the server advertised a named MCP capability.
Parameters
- capability: string
  A top-level capability name such as "tools" or "resources".
Returns boolean
- Defined in core/session.ts:400

unsubscribeFromResource

unsubscribeFromResource(uri: string, options?: RequestOptions): Promise<{}>
Unsubscribe from resource updates.
Parameters
- uri: string
  URI of the resource to unsubscribe from
- Optionaloptions: RequestOptions
  Request options
Returns Promise<{}>
Example
```
await session.unsubscribeFromResource("file:///path/to/file.txt");
```
- Defined in core/session.ts:543

Class MCPConnection

Example

Example

See

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns MCPConnection

Example

Example

Properties

Readonlyconnector

Accessors

info

Returns MCPConnectionInfo

Throws

isConnected

Returns boolean

Example

negotiatedProtocolVersion

Returns string | undefined

protocolEra

Returns ProtocolEra | undefined

serverCapabilities

Returns Record<string, unknown>

serverInfo

Returns MCPServerInfo | null

tools

Returns {}[]

Example

Methods

callTool

Parameters

Returns Promise<{ [key: string]: unknown }>

Example

complete

Parameters

Returns Promise<{ [key: string]: unknown }>

Example

connect

Returns Promise<void>

Example

See

disconnect

Returns Promise<void>

Example

See

getPrompt

Parameters

Returns Promise<{ [key: string]: unknown }>

Example

getRoots

Returns {}[]

Example

See

initialize

Returns Promise<void>

Example

See

listAllResources

Parameters

Returns Promise<{ resources: any[] }>

Example

listPrompts

Returns Promise<{ [key: string]: unknown }>

Example

listResources

Parameters

Returns Promise<{ [key: string]: unknown }>

Example

listResourceTemplates

Parameters

Returns Promise<{ [key: string]: unknown }>

Example

listTools

`Readonly`connector