> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcp-use.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCPClient

> Create and manage MCP client connections

```ts theme={null}
import { MCPClient } from "@mcp-use/client";
```

`MCPClient` stores server configuration and returns [`MCPConnection`](/typescript/api-reference/client/mcp-session) instances. The root export resolves to a Node or browser implementation automatically.

## Constructor

```ts theme={null}
new MCPClient(config?, options?)
```

| Param | Type | Description |
| - | - | - |
| `config` | `MCPClientConfigShape \| string` | Inline config or path to JSON file |
| `options` | `MCPClientOptions` | Code mode, global callbacks |

## Static methods

| Method | Description |
| - | - |
| `fromDict(cfg, options?)` | Create from inline config object |
| `fromConfigFile(path, options?)` | Create from JSON file (Node) |
| `getPackageVersion()` | Installed package version string |
| `loadConfigFile(path)` | Read and parse a config file (Node) |

## Connection lifecycle

| Method | Returns | Description |
| - | - | - |
| `connect(name)` | `Promise<MCPConnection>` | Connect and negotiate protocol (**preferred**) |
| `connectAll()` | `Promise<Record<string, MCPConnection>>` | Connect every configured server |
| `createSession(name, autoInit?)` | `Promise<MCPSession>` | Legacy alias for `connect` |
| `createAllSessions(autoInit?)` | `Promise<Record<string, MCPSession>>` | Legacy alias for `connectAll` |
| `getSession(name)` | `MCPSession \| null` | Get active connection or null |
| `requireSession(name)` | `MCPSession` | Get active connection or throw |
| `getAllActiveSessions()` | `Record<string, MCPSession>` | All active connections |
| `closeSession(name)` | `Promise<void>` | Disconnect one server |
| `closeAllSessions()` | `Promise<void>` | Disconnect all |
| `close()` | `Promise<void>` | Shutdown client (preferred on exit) |

## Configuration

| Method | Description |
| - | - |
| `addServer(name, config)` | Add or replace a server |
| `removeServer(name)` | Remove config and disconnect |
| `getServerNames()` | List configured server names |
| `getServerConfig(name)` | Get one server's config |
| `getConfig()` | Full client config |
| `saveConfig(filepath)` | Write config to JSON (Node) |

## Code mode (Node)

Requires `options.codeMode: true` or a `CodeModeConfig` object.

| Method | Description |
| - | - |
| `executeCode(code, timeout?)` | Run JS/TS with tool access |
| `searchTools(query?, detailLevel?)` | Search tools across sessions |

## Types

### MCPClientConfigShape

```ts theme={null}
interface MCPClientConfigShape {
  mcpServers?: Record<string, ServerConfig>;
  clientInfo?: ClientInfo;
  onSampling?: OnSamplingCallback;
  onElicitation?: OnElicitationCallback;
  onNotification?: OnNotificationCallback;
}
```

Per-server configs can override callbacks. Server-level fields inherit from root when omitted.

### ServerConfig (HTTP)

| Field | Type | Description |
| - | - | - |
| `url` | `string` | MCP HTTP endpoint |
| `headers` | `Record<string, string>` | Request headers |
| `authToken` | `string` | Bearer token |
| `oauth` | `AutoOAuthOptions \| false` | OAuth options or disable |
| `authProvider` | `OAuthClientProvider` | Custom auth provider |
| `detectMixedAuth` | `boolean` | Discover RFC 9728 metadata after anonymous connection; defaults to `true` |
| `onSampling`, `onElicitation`, `onNotification` | callbacks | Per-server overrides |
| `roots` | `Root[]` | Initial roots |
| `timeout` | `number` | Connection timeout (ms) |

### ServerConfig (stdio, Node only)

| Field | Type |
| - | - |
| `command` | `string` |
| `args` | `string[]` |
| `env` | `Record<string, string>` |

### MCPClientOptions

```ts theme={null}
interface MCPClientOptions {
  codeMode?: boolean | CodeModeConfig;
  onSampling?: OnSamplingCallback;
  onElicitation?: OnElicitationCallback;
  onNotification?: OnNotificationCallback;
}
```

## Other exports

Auth: `createOAuthProvider`, `NodeOAuthClientProvider`, `completeOAuthFlow`, `isUnauthorized`, `FileKVStore`

Elicitation helpers: `acceptWithDefaults`, `accept`, `decline`, `cancel`, `validate`, `getDefaults`, `applyDefaults`

Connectors: `HttpConnector`, `StdioConnector`, `BaseConnector`

Types: `MCPConnection`, `MCPSession` (deprecated alias), `MCPConnectionInfo`, `MCPAuthorizationInfo`, `Notification`, `Root`, `Tool`

Re-exports from `@modelcontextprotocol/client`: `auth`, `UnauthorizedError`

## Related

* [`MCPConnection`](/typescript/api-reference/client/mcp-session)
* [Client overview](/typescript/client/index)
* [Code mode](/typescript/api-reference/client/code-mode)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.