Skip to main content
View the source code for this module on GitHub: https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/src/session.ts
MCPSession represents one live connection to one MCP server. It wraps a connector and exposes high-level methods for lifecycle, tools, resources, prompts, completion, roots, notifications, and raw requests. Sessions are usually created with MCPClient.createSession(). 
import { MCPClient, type MCPSession } from "mcp-use";

const client = new MCPClient({
  mcpServers: {
    api: { url: "http://localhost:3000/mcp" },
  },
});

const session = await client.createSession("api");
const result = await session.callTool("search", { query: "mcp" });

​
Constructor

Creates a session around a connector. This is an advanced path; most applications should create sessions through MCPClient. Parameters
​
connector
BaseConnector
required
Connector that owns the transport and protocol client.
​
autoConnect
boolean
default:"true"
When true, initialize() connects before running the MCP initialize handshake.
Signature 
constructor(connector: BaseConnector, autoConnect?: boolean)

​
Lifecycle

​
connect

Starts the underlying transport without running the MCP initialize handshake. Returns
​
returns
Promise<void>
Signature 
connect(): Promise<void>

​
initialize

Runs the MCP initialize handshake. If autoConnect is true and the session is not connected, this method connects first. Returns
​
returns
Promise<void>
Example 
const session = await client.createSession("api", false);
await session.connect();
await session.initialize();
Signature 
initialize(): Promise<void>

​
disconnect

Closes the underlying transport and releases connection resources. Returns
​
returns
Promise<void>
Signature 
disconnect(): Promise<void>

​
isConnected

Returns whether the underlying connector is connected. Returns
​
returns
boolean
Signature 
get isConnected(): boolean

​
Tools

​
tools

Returns the connector’s cached tool list. Returns
​
returns
Tool[]
Signature 
get tools(): Tool[]

​
listTools

Fetches the current tool list from the server. Parameters
​
options
RequestOptions | undefined
default:"undefined"
Optional MCP SDK request options.
Returns
​
returns
Promise<Tool[]>
Signature 
listTools(options?: RequestOptions): Promise<Tool[]>

​
callTool

Calls a tool on the server. Parameters
​
name
string
required
Tool name.
​
args
Record<string, any>
default:"{}"
Tool arguments.
​
options
RequestOptions | undefined
default:"undefined"
Optional MCP SDK request options, such as timeout and progress handling.
Returns
​
returns
Promise<CallToolResult>
Example 
const result = await session.callTool("add", { a: 5, b: 3 });
console.log(result.content);
Signature 
callTool(
  name: string,
  args?: Record<string, any>,
  options?: RequestOptions
): Promise<CallToolResult>

​
Resources

​
listResources

Lists resources from the server with optional pagination. Parameters
​
cursor
string | undefined
default:"undefined"
Pagination cursor returned by a previous response.
​
options
RequestOptions | undefined
default:"undefined"
Optional MCP SDK request options.
Returns
​
returns
Promise<ListResourcesResult>
Signature 
listResources(cursor?: string, options?: RequestOptions): Promise<ListResourcesResult>

​
listAllResources

Lists every resource from the server by following pagination. Parameters
​
options
RequestOptions | undefined
default:"undefined"
Optional MCP SDK request options.
Returns
​
returns
Promise<ListResourcesResult>
Signature 
listAllResources(options?: RequestOptions): Promise<ListResourcesResult>

​
listResourceTemplates

Lists parameterized resource templates exposed by the server. Parameters
​
options
RequestOptions | undefined
default:"undefined"
Optional MCP SDK request options.
Returns
​
returns
Promise<ListResourceTemplatesResult>
Signature 
listResourceTemplates(options?: RequestOptions): Promise<ListResourceTemplatesResult>

​
readResource

Reads a resource by URI. Parameters
​
uri
string
required
Resource URI.
​
options
RequestOptions | undefined
default:"undefined"
Optional MCP SDK request options.
Returns
​
returns
Promise<ReadResourceResult>
Example 
const resource = await session.readResource("file:///tmp/report.txt");
console.log(resource.contents);
Signature 
readResource(uri: string, options?: RequestOptions): Promise<ReadResourceResult>

​
subscribeToResource

Subscribes to resource update notifications for a URI. Parameters
​
uri
string
required
Resource URI to subscribe to.
​
options
RequestOptions | undefined
default:"undefined"
Optional MCP SDK request options.
Returns
​
returns
Promise<SubscribeResult>
Signature 
subscribeToResource(uri: string, options?: RequestOptions): Promise<SubscribeResult>

​
unsubscribeFromResource

Unsubscribes from resource update notifications for a URI. Parameters
​
uri
string
required
Resource URI to unsubscribe from.
​
options
RequestOptions | undefined
default:"undefined"
Optional MCP SDK request options.
Returns
​
returns
Promise<UnsubscribeResult>
Signature 
unsubscribeFromResource(uri: string, options?: RequestOptions): Promise<UnsubscribeResult>

​
Prompts and completion

​
listPrompts

Lists prompt templates exposed by the server. Returns
​
returns
Promise<ListPromptsResult>
Signature 
listPrompts(): Promise<ListPromptsResult>

​
getPrompt

Fetches a prompt by name with arguments. Parameters
​
name
string
required
Prompt name.
​
args
Record<string, any>
required
Prompt arguments.
Returns
​
returns
Promise<GetPromptResult>
Signature 
getPrompt(name: string, args: Record<string, any>): Promise<GetPromptResult>

​
complete

Requests completion suggestions for a prompt or resource template argument. Parameters
​
params
CompleteRequestParams
required
Completion request parameters.
​
options
RequestOptions | undefined
default:"undefined"
Optional MCP SDK request options.
Returns
​
returns
Promise<CompleteResult>
Example 
const result = await session.complete({
  ref: { type: "ref/prompt", name: "translate" },
  argument: { name: "language", value: "py" },
});
Signature 
complete(
  params: CompleteRequestParams,
  options?: RequestOptions
): Promise<CompleteResult>

​
Roots and notifications

​
setRoots

Sets the roots advertised to the server and sends the corresponding notification. Parameters
​
roots
Root[]
required
Roots with file:// URIs and optional names.
Returns
​
returns
Promise<void>
Example 
await session.setRoots([
  { uri: "file:///Users/alex/project", name: "Project" },
]);
Signature 
setRoots(roots: Root[]): Promise<void>

​
getRoots

Returns the roots currently advertised to the server. Returns
​
returns
Root[]
Signature 
getRoots(): Root[]

​
on

Registers a session event handler. The current public event is "notification". Parameters
​
event
"notification"
required
Event name.
​
handler
NotificationHandler
required
Handler called with each notification.
Returns
​
returns
void
Example 
session.on("notification", async (notification) => {
  if (notification.method === "notifications/tools/list_changed") {
    await session.listTools();
  }
});
Signature 
on(event: "notification", handler: NotificationHandler): void

​
Server metadata

​
serverCapabilities

Returns server capabilities from the initialize response. Returns
​
returns
Record<string, unknown>
Signature 
get serverCapabilities(): Record<string, unknown>

​
serverInfo

Returns server name and version from the initialize response, or null when unavailable. Returns
​
returns
{ name: string; version?: string } | null
Signature 
get serverInfo(): { name: string; version?: string } | null

​
Raw requests

​
request

Sends a raw JSON-RPC request through the connector. Use this for custom MCP methods when no helper exists. Parameters
​
method
string
required
MCP method name.
​
params
Record<string, any> | null
default:"null"
Request parameters.
​
options
RequestOptions | undefined
default:"undefined"
Optional MCP SDK request options.
Returns
​
returns
Promise<unknown>
Signature 
request(
  method: string,
  params?: Record<string, any> | null,
  options?: RequestOptions
): Promise<unknown>

​
Types

​
Root

Directory or file root advertised to a server. Fields
​
uri
string
Root URI. Use file:// URIs.
​
name
string
Optional display name.

​
Tool

Tool metadata returned by listTools() and the tools getter. This type is re-exported from the MCP SDK.

​
CallToolResult

Result returned by callTool(). This type is re-exported from the MCP SDK.

​
Notification

Server notification object passed to notification handlers. This type is re-exported from the MCP SDK.
  • MCPClient: create sessions and manage client configuration.
  • Tools: guide to listing and calling tools.
  • Resources: guide to reading resources.
  • Prompts: guide to listing and getting prompts.
  • Notifications: guide to notification handlers and roots.