> ## 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)