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

# Migrate to v2

> Migrate client, agent, and React connection code from mcp-use 1.x

This guide updates applications from the mcp-use 1.x client surface to the v2
packages. It covers client, agent, and React connection code.

<Warning>
  Server and interactive UI APIs also have breaking changes. Do not assume that
  existing server or widget code can be carried forward unchanged. Follow the
  [server guide](/v2/typescript/server) and
  [MCP Apps guide](/v2/typescript/mcp-apps) for those parts of your application.
</Warning>

## 1. Update the runtime and packages

The current client and agent packages require Node.js `>=22.22.2` and are
ESM-only.

```bash theme={null}
npm install @mcp-use/client @mcp-use/agent
```

Install `mcp-use` when the same project builds a server or MCP App View:

```bash theme={null}
npm install mcp-use
```

Ensure your project emits ESM and your bundler respects the package's `node` and
`browser` export conditions.

## 2. Move imports to their package entry points

| 1.x surface | Current import | Purpose |
| - | - | - |
| `MCPClient`, connectors, OAuth, and sessions from `mcp-use` | `@mcp-use/client` | Node or browser MCP client |
| `useMcp` and `McpClientProvider` from `mcp-use/react` | `@mcp-use/client/react` | React connection management |
| `MCPAgent` and `PROMPTS` from `mcp-use` | `@mcp-use/agent` | Native agent |
| LangChain agent compatibility and `ServerManager` | `@mcp-use/agent/langchain` | Optional LangChain integration |
| Widget hooks such as `useWidget` (removed) | `mcp-use/react` View hooks | Code running inside MCP App Views |
| `MCPServer` and server capabilities | `mcp-use` | MCP server |

```typescript theme={null}
import { MCPClient } from "@mcp-use/client";
import { MCPAgent, PROMPTS } from "@mcp-use/agent";
```

For the optional LangChain compatibility layer:

```typescript theme={null}
import {
  LangChainMCPAgent,
  ServerManager,
} from "@mcp-use/agent/langchain";
```

The native `MCPAgent` and the LangChain compatibility agent are separate public
entry points. Import `ServerManager` only from the LangChain entry.

### Removed client subpaths

The client package exports its conditional root, the `./react` entry, and a
`./sandbox` entry for the MCP Apps sandbox proxy document. Replace these removed
imports:

| Removed import | Use instead |
| - | - |
| `@mcp-use/client/browser` | `@mcp-use/client` in a browser build |
| `@mcp-use/client/auth` | `@mcp-use/client` |
| `@mcp-use/client/auth/node` | Node OAuth helpers from `@mcp-use/client` |

The root entry resolves to the Node build under the `node` condition and to the
browser-safe build under the `browser` or default condition.

## 3. Update the connection API

Use `connect()` and `connectAll()`:

```typescript theme={null}
import {
  MCPClient,
  type MCPConnection,
} from "@mcp-use/client";

const client = new MCPClient({
  mcpServers: {
    demo: { url: "https://api.example.com/mcp" },
  },
});

try {
  const connection: MCPConnection = await client.connect("demo");
  await connection.callTool("echo", { message: "hello" });
} finally {
  await client.close();
}
```

`createSession()` and `createAllSessions()` remain as deprecated compatibility
aliases. `MCPSession` is a deprecated runtime and type alias for
`MCPConnection`.

Every connection exposes the negotiated server information:

```typescript theme={null}
console.log(connection.info.protocolEra);
console.log(connection.info.protocolVersion);
console.log(connection.info.capabilities);
console.log(connection.info.instructions);
```

## 4. Configure protocol negotiation

The public configuration field is `protocolNegotiation`, not
`versionNegotiation`.

HTTP connections default to `protocolNegotiation: "auto"`: they probe the
sessionless protocol and fall back to the sessionful protocol. Stdio defaults to
`"legacy"` to avoid probing a process that may be launched for one invocation.

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

const client = new MCPClient({
  mcpServers: {
    compatible: {
      url: "https://api.example.com/mcp",
      protocolNegotiation: "auto",
    },
  },
});
```

The accepted values are `"auto"`, `"legacy"`, and `{ pin: "2026-07-28" }`.
There is no `"modern"` value; pin the modern protocol version to use the
sessionless protocol without fallback.

The client CLI exposes the same choices as `--protocol auto`, `legacy`, and
`modern`. Its `modern` mode uses `{ pin: "2026-07-28" }`:

```bash theme={null}
mcp-use client connect demo https://api.example.com/mcp --protocol auto
mcp-use client connect legacy https://legacy.example.com/mcp --protocol legacy
mcp-use client connect modern https://modern.example.com/mcp --protocol modern
```

There is no `--negotiate` flag.

## 5. Rename client configuration

Search your client configuration for the removed 1.x names and update them:

| 1.x name | Current name |
| - | - |
| `samplingCallback` | `onSampling` |
| `elicitationCallback` | `onElicitation` |
| `auth_token` | `authToken` |
| `customHeaders` | `headers` |
| `clientConfig` | `clientInfo` |
| `debug` | `logLevel` on `useMcp` |
| `BrowserTelemetry` | `Telemetry` |
| `ResourceTemplate` client type | `ResourceTemplateType` |

`MCPClient` has no `logLevel` option. Set `MCP_USE_LOG_LEVEL` (for example
`debug`; `DEBUG=2` also works) in the environment, or assign `logger.level` on
the `logger` exported by `@mcp-use/client`.

Sampling, elicitation, and notification callbacks can be set as global client
defaults or on an individual server configuration. Per-server callbacks take
precedence.

## 6. Update authentication behavior

`MCPClient` automatically creates an OAuth provider for HTTP servers that do not
already configure an `authProvider`, `authToken`, `oauth: false`, or an
`Authorization` header.

* Node OAuth opens a browser and waits for its loopback callback.
* The browser root client opens a popup by default and can use a redirect.
* `useMcp` and `McpClientProvider` default to
  `preventAutoAuth: true`. Handle `pending_auth` and call `authenticate()`.

```tsx theme={null}
import { useMcpServer } from "@mcp-use/client/react";

export function ServerAuth() {
  const server = useMcpServer("demo");

  if (server?.state === "pending_auth") {
    return (
      <button onClick={() => void server.authenticate()}>
        Sign in
      </button>
    );
  }

  return null;
}
```

For a React OAuth callback route, import `onMcpAuthorization` from
`@mcp-use/client/react`. A non-React browser build can use the browser
conditional root export.

Pre-registered clients also have different configuration shapes:

* `MCPClient`: `oauth.staticClientInfo.client_id`
* React: `oauth.clientId`

See [Authentication](/v2/typescript/client/authentication) for complete Node,
browser, React, proxy, and public-client examples.

## 7. Update React connection code and Views

Move connection management to `@mcp-use/client/react`:

| 1.x usage | Current usage |
| - | - |
| `useMcp` from `mcp-use/react` | `useMcp` from `@mcp-use/client/react` |
| `McpServerOptions` | `McpServerConfig` (`McpServerOptions` is deprecated) |
| Server config `name` used as a display label | `displayName` |
| Displayed `server.name` | Negotiated `server.serverInfo?.name` |

`@mcp-use/client/react` also exports `ViewRenderer` for a host application that
renders MCP App Views.

Code running inside a View stays in `mcp-use/react`, but must use focused View
hooks such as `useToolContext`, `useCallTool`, and `useViewState`. The widget
hooks `useWidget`, `useWidgetProps`, and `useWidgetState` were removed; see the
[server migration guide](/v2/typescript/server/migration) for their
replacements.

## 8. Replace removed low-level exports

The client root no longer re-exports the old Zod `*Schema` constants or
`JSONSchemaToZod`.

* Import protocol types from `@modelcontextprotocol/client`.
* Use `ResourceTemplateType` for the protocol resource-template type.
* Use Zod 4's `z.fromJSONSchema()` when you need to convert JSON Schema.

The current telemetry implementation does not bundle the PostHog browser or
Node SDKs. If you used the old telemetry override, note that `telFetch` is now a
non-throwing `(url, init) => Promise<void>` helper.

Do not remove `@modelcontextprotocol/ext-apps` based on the old migration notes;
the current client still uses it for MCP Apps bridging.

## 9. Review server and MCP App changes

The server is now built around the root `mcp-use` entry, a stateless
`MCPServer`, and standard protocol result envelopes. Review tool, resource,
prompt, middleware, authentication, and deployment APIs against the
[server guide](/v2/typescript/server).

Interactive results use MCP Apps Views. Bind a View to a tool, return
model-facing `content` and View props in `structuredContent`, and consume the
result with focused hooks such as `useToolContext`. The widget hooks were
removed; the deprecated `widget()` response helper remains only for
compatibility. Follow the
[MCP Apps guide](/v2/typescript/mcp-apps) before updating interactive UI code.

## 10. Check Inspector callback URLs

The standalone Inspector OAuth callback resolves relative to the configured
Inspector base path. With the normal `/inspector` base, the callback is
`/inspector/oauth/callback`; deployments under another base use that base's
`/oauth/callback`.

If you run a custom OAuth proxy, continue to bind upstream targets to
SDK-discovered metadata. The Inspector proxy rejects arbitrary upstream target
URLs.

## Migration checklist

<Steps>
  <Step title="Update the runtime and packages">
    Use Node.js `>=22.22.2`, install the v2 packages, and confirm ESM output.
  </Step>

  <Step title="Fix imports">
    Search for client and agent imports from `mcp-use`, removed
    `@mcp-use/client/*` subpaths, and connection hooks from `mcp-use/react`.
  </Step>

  <Step title="Separate native and LangChain agents">
    Keep `MCPAgent` and `PROMPTS` on `@mcp-use/agent`; move
    `ServerManager` and LangChain compatibility imports to
    `@mcp-use/agent/langchain`.
  </Step>

  <Step title="Rename configuration">
    Search for `versionNegotiation`, `samplingCallback`,
    `elicitationCallback`, `auth_token`, `customHeaders`, `clientConfig`, and
    `debug`.
  </Step>

  <Step title="Use the connection API">
    Replace `createSession` and `createAllSessions` calls with `connect` and
    `connectAll`; replace `MCPSession` annotations with `MCPConnection`.
  </Step>

  <Step title="Update OAuth UI">
    Handle React's `pending_auth` state, use the correct pre-registered client
    shape for each API, and verify callback and proxy URLs.
  </Step>

  <Step title="Update Views">
    Separate React connection management from code that runs inside an MCP App
    View, then replace the removed widget hooks with View hooks.
  </Step>

  <Step title="Verify each environment">
    Type-check Node, browser, and React entry points independently, then connect
    to one sessionful and one sessionless server if your application supports
    both.
  </Step>
</Steps>

## Related

* [Client overview](/v2/typescript/client/index)
* [Authentication](/v2/typescript/client/authentication)
* [React integration](/v2/typescript/client/usemcp)
* [Server guide](/v2/typescript/server)
* [MCP Apps guide](/v2/typescript/mcp-apps)


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