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

# Authentication

> OAuth and bearer tokens for MCP client connections

HTTP connections support automatic OAuth, pre-registered public clients,
bearer tokens, custom headers, and custom authentication providers.

## Automatic OAuth with `MCPClient`

`MCPClient` creates an OAuth provider for an HTTP server unless the server
configuration already supplies an `authProvider`, `authToken`, `oauth: false`,
or an `Authorization` header.

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

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

try {
  await client.connect("demo");
} finally {
  await client.close();
}
```

In Node.js, the default provider opens a browser and waits for its loopback
callback. In the browser build, the default provider opens a popup; set
`useRedirectFlow: true` inside the server's `oauth` options to use a full-page
redirect.

Pass a custom `authProvider` when your application owns the authorization flow.

## Whole-server and mixed OAuth

Whole-server OAuth rejects the MCP connection until the user authorizes. A
mixed-auth server instead allows anonymous connection and public operations,
then requires OAuth only for protected tools, resources, or prompts.

When a successfully connected server publishes
[RFC 9728 protected-resource metadata](https://www.rfc-editor.org/rfc/rfc9728.html),
`MCPClient` exposes it as mixed auth without forcing authorization:

```typescript theme={null}
const connection = await client.connect("demo");
const authorization = await connection.discoverAuthorization();

if (authorization?.mode === "mixed" && !authorization.authenticated) {
  console.log("Public operations are available without signing in.");

  // Optional: authenticate now instead of waiting for a protected operation.
  await connection.authenticate();
}
```

After discovery, `connection.authorization` and `connection.info.authorization`
expose the same state. It includes `resource` and `scopesSupported` when the
protected-resource metadata advertises them. Mixed-auth discovery is
best-effort and defaults to enabled for HTTP servers with an OAuth provider.
Call `discoverAuthorization()` when using `MCPClient` directly; React performs
the same discovery after publishing the ready connection. Set `detectMixedAuth:
false` on the server configuration to skip the discovery request.

If the client stays anonymous, a later wire-level OAuth challenge from a
protected operation starts the official SDK flow. Automatic flows finish OAuth
through the active transport and retry the logical operation once. Explicit
browser flows surface the prepared authentication action so the host can
authenticate and retry. MCP tool results with `isError: true` or auth-like text
are application errors, not OAuth challenges.

## React: explicit authentication

React connection APIs use an explicit authorization step by default.
`preventAutoAuth` defaults to `true`, so an unauthorized connection enters
`pending_auth` until the user calls `authenticate()`.

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

export function ProtectedConnection() {
  const mcp = useMcp({
    url: "https://api.example.com/mcp",
  });

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

  if (
    mcp.authorization?.mode === "mixed" &&
    !mcp.authorization.authenticated
  ) {
    return (
      <>
        <p>Public tools are available. Sign in to use protected tools.</p>
        <button onClick={() => void mcp.authenticate()}>Authenticate</button>
      </>
    );
  }

  return <p>Connection state: {mcp.state}</p>;
}
```

Set `preventAutoAuth: false` on `useMcp` or a
`McpClientProvider` server configuration to start authorization automatically.
Popup mode is the default; set the top-level React option
`useRedirectFlow: true` for a full-page redirect.

On your callback route, import `onMcpAuthorization` from
`@mcp-use/client/react`. See
[React integration](/v2/typescript/client/usemcp#oauth-callback).

## Pre-registered clients

The `MCPClient` configuration uses
`oauth.staticClientInfo.client_id`:

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

const client = new MCPClient({
  mcpServers: {
    slack: {
      url: "https://mcp.example.com/mcp",
      oauth: {
        staticClientInfo: {
          client_id: "my-client-id",
        },
        clientMetadataUrl:
          "https://app.example.com/.well-known/oauth-client-metadata.json",
        scope: "openid profile",
      },
    },
  },
});
```

React uses a different, UI-oriented shape:

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

const mcp = useMcp({
  url: "https://mcp.example.com/mcp",
  oauth: {
    clientId: "my-client-id",
    clientMetadataUrl:
      "https://app.example.com/.well-known/oauth-client-metadata.json",
    scope: "openid profile",
  },
});
```

Browser OAuth clients are public PKCE clients. Do not put a `client_secret` in
browser configuration; `BrowserOAuthClientProvider` rejects one in
`staticClientInfo`.

## OAuth proxy in the browser

Use an OAuth proxy when the authorization server's metadata, token, or
registration endpoints do not support browser CORS:

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

const mcp = useMcp({
  url: "https://mcp.example.com/mcp",
  oauthProxyUrl: "https://app.example.com/api/mcp-oauth",
});
```

For the browser `MCPClient`, `oauth.oauthProxyUrl` configures the proxy and
`oauth.proxyOAuthRequests` controls whether OAuth HTTP requests use it. The
latter defaults to `true` when the browser provider is created. React routes its
OAuth requests through the configured `oauthProxyUrl`; it does not expose
`proxyOAuthRequests` as a `useMcp` option.

## Manual browser authorization

Construct a `BrowserOAuthClientProvider` with `preventAutoAuth: true` and pass it
to the browser client when you need to present the authorization URL yourself:

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

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

try {
  await client.connect("api");
} catch (error) {
  if (!isUnauthorized(error)) throw error;

  const authorizationUrl = authProvider.getLastAttemptedAuthUrl();
  if (authorizationUrl) {
    window.location.assign(authorizationUrl);
  }
}
```

`getLastAttemptedAuthUrl()` returns the URL for the current provider instance.
It is kept in memory only, so start a new authorization attempt after a page
reload. The auto-provisioned browser provider also accepts
`oauth.preventAutoAuth`, but an explicit provider gives your application access
to the prepared URL.

## Bearer tokens

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

const client = new MCPClient({
  mcpServers: {
    api: {
      url: "https://api.example.com/mcp",
      authToken: process.env.API_KEY,
    },
  },
});
```

An explicit `Authorization` header also disables automatic OAuth:

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

const client = new MCPClient({
  mcpServers: {
    api: {
      url: "https://api.example.com/mcp",
      headers: {
        Authorization: `Bearer ${process.env.API_KEY}`,
      },
    },
  },
});
```

## `MCPClient` server fields

| Field             | Description                                                                  |
| ----------------- | ---------------------------------------------------------------------------- |
| `authToken`       | Bearer token                                                                 |
| `headers`         | Custom HTTP headers                                                          |
| `oauth`           | Automatic OAuth options, or `false` to disable automatic OAuth               |
| `authProvider`    | Custom SDK-compatible provider                                               |
| `detectMixedAuth` | Discover optional mixed OAuth after anonymous connection; defaults to `true` |

## Node OAuth helpers

```typescript theme={null}
import {
  createOAuthProvider,
  NodeOAuthClientProvider,
  completeOAuthFlow,
  isUnauthorized,
  FileKVStore,
} from "@mcp-use/client";
```

Use these exports for headless scripts, custom storage, or an authorization flow
you manage directly.