mcp-use - The fullstack MCP framework to develop MCP Apps for ChatGPT / Claude and MCP Servers for AI Agents.

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.

​Constructor

​Lifecycle

​connect

​initialize

​disconnect

​isConnected

​Tools

​tools

​listTools

​callTool

​Resources

​listResources

​listAllResources

​listResourceTemplates

​readResource

​subscribeToResource

​unsubscribeFromResource

​Prompts and completion

​listPrompts

​getPrompt

​complete

​Roots and notifications

​setRoots

​getRoots

​on

​Server metadata

​serverCapabilities

​serverInfo

​Raw requests

​request

​Types

​Root

​Tool

​CallToolResult

​Notification

​Related

Constructor

Lifecycle

connect

initialize

disconnect

isConnected

Tools

tools

listTools

callTool

Resources

listResources

listAllResources

listResourceTemplates

readResource

subscribeToResource

unsubscribeFromResource

Prompts and completion

listPrompts

getPrompt

complete

Roots and notifications

setRoots

getRoots

on

Server metadata

serverCapabilities

serverInfo

Raw requests

request

Types

Root

Tool

CallToolResult

Notification

Related