mcp-use - Connect Any LLM to Any MCP Server

The mcp-use client supports multiple authentication methods for secure connections to MCP servers, including OAuth 2.1 with automatic token management, bearer token authentication, and custom authentication providers.

Supported Authentication Methods

OAuth 2.1: Complete OAuth flow with automatic Dynamic Client Registration (DCR)
Bearer Tokens: API key and token-based authentication
Custom Headers: Flexible authentication header support

OAuth Authentication

OAuth provides secure, token-based authentication with automatic token refresh and user consent flows.

import { useMcp } from "mcp-use/react";

function MyComponent() {
  const mcp = useMcp({
    url: "http://localhost:3000/mcp",
    callbackUrl: "http://localhost:3000/callback",
  });

  // Handle authentication states
  if (mcp.state === "pending_auth") {
    return <button onClick={mcp.authenticate}>Authenticate with OAuth</button>;
  }

  if (mcp.state === "authenticating") {
    return <div>Authenticating...</div>;
  }

  if (mcp.state === "ready") {
    return <div>Connected! {mcp.tools.length} tools available</div>;
  }

  return <div>Connecting...</div>;
}

Custom OAuth Provider (Headless/Testing)

If you run in non-browser environments (tests, headless runners, custom redirects), you can inject your own OAuth provider.

import { useMcp } from "mcp-use/react";
import { MyOAuthClientProvider } from "./my-oauth-provider";

const mcp = useMcp({
  url: "http://localhost:3000/mcp",
  authProvider: new MyOAuthClientProvider(),
});

When authProvider is provided, useMcp uses that provider directly instead of creating the default browser OAuth provider internally.

Bearer Token Authentication

For servers requiring API keys or bearer tokens:

import { useMcp } from 'mcp-use/react'

function MyComponent() {
const mcp = useMcp({
url: 'http://localhost:3000/mcp',
headers: {
Authorization: 'Bearer sk-your-api-key-here'
}
})

// Use mcp.tools, mcp.callTool, etc.
}

Node.js Client Authentication

For server-side Node.js applications, use MCPClient with bearer tokens or custom headers. OAuth flows are browser-only and not available in Node.js environments.

Bearer Token Authentication

The simplest way to authenticate with API-based MCP servers:

import { MCPClient } from 'mcp-use'

const config = {
mcpServers: {
"my-server": {
url: "https://api.example.com/mcp",
authToken: "sk-your-api-key-here"
}
}
}

const client = MCPClient.fromDict(config)

Custom Headers

For servers requiring custom authentication headers or additional metadata:

import { MCPClient } from "mcp-use";

const config = {
  mcpServers: {
    "my-server": {
      url: "https://api.example.com/mcp",
      headers: {
        Authorization: "Bearer sk-your-api-key",
        "X-API-Version": "2024-01-01",
        "X-Custom-Header": "value",
      },
    },
  },
};

const client = MCPClient.fromDict(config);

Configuration File

Load authentication settings from a JSON configuration file:

import { MCPClient } from 'mcp-use'

// Constructor accepts file path directly
const client = new MCPClient('./mcp-config.json')

// Or use fromDict with imported config
import config from './mcp-config.json'
const client = MCPClient.fromDict(config)

Best Practice: Store sensitive tokens in environment variables and reference them in your configuration instead of hardcoding them in files.

CLI Authentication

The mcp-use CLI client supports bearer token authentication for connecting to secured MCP servers:

# Connect with bearer token
npx mcp-use client connect https://api.example.com/mcp \
  --name my-server \
  --auth sk-your-api-key

# List tools (uses saved authentication)
npx mcp-use client tools list

# Call a tool
npx mcp-use client tools call send_email '{"to":"[email protected]"}'

# Disconnect
npx mcp-use client disconnect my-server

The CLI automatically saves authentication tokens in ~/.mcp-use/cli-sessions.json for future sessions.

For complete CLI documentation including stdio connections, session management, and interactive mode, see the CLI Client Guide.

OAuth Flow Modes

mcp-use supports two OAuth flow modes for client applications: Opens OAuth authorization in a popup window. Best for desktop and web applications. Advantages:

User stays on the same page
Better UX for web applications
No navigation interruption

Usage:

const mcp = useMcp({
  url: "http://localhost:3000/mcp",
  callbackUrl: "http://localhost:3000/callback",
  // Popup flow is the default
});

Redirect Flow

Redirects the current window to the OAuth provider, then back to your app. Advantages:

Works in all browsers (popup blockers won’t interfere)
Better for mobile browsers
More reliable across different environments

Usage:

const mcp = useMcp({
  url: "http://localhost:3000/mcp",
  callbackUrl: "http://localhost:3000/callback",
  useRedirectFlow: true, // Enable redirect flow
});

Setup for Redirect Flow:

Create a callback page in your app:

// pages/callback.tsx or app/callback/page.tsx
import { onMcpAuthorization } from "mcp-use/auth";
import { useEffect, useState } from "react";

export default function OAuthCallback() {
  const [status, setStatus] = useState<"processing" | "success" | "error">(
    "processing"
  );

  useEffect(() => {
    onMcpAuthorization()
      .then(() => {
        setStatus("success");
        // Redirect back to main app
        setTimeout(() => (window.location.href = "/"), 1000);
      })
      .catch((err) => {
        setStatus("error");
        console.error("Auth failed:", err);
      });
  }, []);

  if (status === "processing") {
    return <div>Completing authentication...</div>;
  }
  if (status === "success") {
    return <div>Success! Redirecting...</div>;
  }
  return <div>Authentication failed</div>;
}

Configure your callback URL to match this route:

const mcp = useMcp({
  url: "http://localhost:3000/mcp",
  callbackUrl: "http://localhost:3000/callback", // Your callback page
  useRedirectFlow: true,
});

Manual Authentication Control

By default, mcp-use requires explicit user action to trigger OAuth authentication. When a server requires authentication, the connection enters pending_auth state and you must call the authenticate() method:

const mcp = useMcp({
  url: "http://localhost:3000/mcp",
  // preventAutoAuth: true is the default
});

// Manually trigger authentication when ready
if (mcp.state === "pending_auth") {
  return <button onClick={mcp.authenticate}>Sign in to continue</button>;
}

To enable automatic OAuth flow (legacy behavior), set preventAutoAuth: false:

const mcp = useMcp({
  url: "http://localhost:3000/mcp",
  preventAutoAuth: false, // Auto-trigger OAuth popup
});

OAuth Flow Process

When OAuth authentication is required:

Configuration Options

Node.js Client Configuration Parameters

Parameter	Type	Required	Description
`url`	string	Yes	MCP server endpoint URL
`authToken`	string	No	Bearer token for authentication (added to Authorization header)
`auth_token`	string	No	Alternative snake_case form of `authToken` (for Python config compatibility)
`headers`	object	No	Custom HTTP headers including authentication headers

Configuration Compatibility: Both authToken (camelCase) and auth_token (snake_case) are accepted for token-based authentication. Use authToken for TypeScript conventions; auth_token is supported for compatibility with Python-style configurations.

OAuth Configuration Parameters (Browser Only)

Parameter	Type	Required	Description
`client_id`	string	No*	OAuth client ID (required if not using DCR)
`client_secret`	string	No	OAuth client secret (required if not using DCR)
`scope`	string	No	OAuth scopes to request
`callback_port`	integer	No	Port for OAuth callback (default: 8080)
`oauth_provider`	object	No	OAuth provider metadata

*Required unless using Dynamic Client Registration

Port Configuration

Default Port: 8080
Custom Ports: Any available port (e.g., 8081, 8082, 3000)
Port Conflicts: mcp-use will check if the port is available before starting OAuth flow

Example Servers that support OAuth

OAuth with DCR Support

Linear: https://mcp.linear.app/mcp

OAuth with Manual Registration

GitHub: https://api.githubcopilot.com/mcp/

Bearer Token

Most API-based MCP servers

Check your server’s documentation for specific authentication requirements and supported methods.

Get Started

MCP Agent

MCP Client

MCP Server

Development

Authentication

Supported Authentication Methods

OAuth Authentication

Custom OAuth Provider (Headless/Testing)

Bearer Token Authentication

Node.js Client Authentication

Bearer Token Authentication

Custom Headers

Configuration File

CLI Authentication

OAuth Flow Modes

Redirect Flow

Manual Authentication Control

OAuth Flow Process

Configuration Options

Node.js Client Configuration Parameters

OAuth Configuration Parameters (Browser Only)

Port Configuration

Example Servers that support OAuth

OAuth with DCR Support

OAuth with Manual Registration

Bearer Token

Get Started

MCP Agent

MCP Client

MCP Server

Development

​Supported Authentication Methods

​OAuth Authentication

​Custom OAuth Provider (Headless/Testing)

​Bearer Token Authentication

​Node.js Client Authentication

​Bearer Token Authentication

​Custom Headers

​Configuration File

​CLI Authentication

​OAuth Flow Modes

​Popup Flow (Default)

​Redirect Flow

​Manual Authentication Control

​OAuth Flow Process

​Configuration Options

​Node.js Client Configuration Parameters

​OAuth Configuration Parameters (Browser Only)

​Port Configuration

​Example Servers that support OAuth

​OAuth with DCR Support

​OAuth with Manual Registration

​Bearer Token

Supported Authentication Methods

OAuth Authentication

Custom OAuth Provider (Headless/Testing)

Bearer Token Authentication

Node.js Client Authentication

Bearer Token Authentication

Custom Headers

Configuration File

CLI Authentication

OAuth Flow Modes

Popup Flow (Default)

Redirect Flow

Manual Authentication Control

OAuth Flow Process

Configuration Options

Node.js Client Configuration Parameters

OAuth Configuration Parameters (Browser Only)

Port Configuration

Example Servers that support OAuth

OAuth with DCR Support

OAuth with Manual Registration

Bearer Token