Authentication Overview

Overview

MCP servers can require authentication to protect resources and control access. mcp-use handles authentication automatically based on your configuration.

Choose Your Method

Bearer Token

Simplest optionUse a static API key or token. Best for services that issue long-lived credentials.

"auth": "sk-your-api-key"

OAuth 2.1

MCP standardFull OAuth flow with automatic discovery, PKCE, and token refresh. Required by many MCP servers.

"auth": { "scope": "read write" }

Custom Auth

Full controlUse any httpx.Auth object for Basic, Digest, or custom authentication schemes.

"auth": BasicAuth("user", "pass")

Quick Start Examples

OAuth (Auto)
OAuth (Pre-registered)
Bearer Token
No Auth

For servers with OAuth support, just provide the URL:

from mcp_use import MCPClient

config = {
    "mcpServers": {
        "linear": {
            "url": "https://mcp.linear.app/sse"
            # OAuth discovery + DCR happens automatically
        }
    }
}

client = MCPClient(config=config)

mcp-use will:

Discover the authorization server
Register a client (or use CIMD/pre-registered credentials)
Open your browser for authorization
Store and refresh tokens automatically

For servers requiring manual OAuth app registration:

config = {
    "mcpServers": {
        "github": {
            "url": "https://api.githubcopilot.com/mcp/",
            "auth": {
                "client_id": "your-github-client-id",
                "client_secret": "your-github-client-secret",
                "scope": "repo",
                "callback_port": 8080
            }
        }
    }
}

For API keys or static tokens:

import os

config = {
    "mcpServers": {
        "api": {
            "url": "https://api.example.com/mcp/sse",
            "auth": os.getenv("API_KEY")
        }
    }
}

For public servers:

config = {
    "mcpServers": {
        "public": {
            "url": "https://public.example.com/mcp/sse"
        }
    }
}

Token Storage

Authentication tokens are stored securely on disk:

~/.mcp_use/tokens/
├── {server}.json                    # Access tokens
└── registrations/
    └── {server}_registration.json   # OAuth client credentials

Add ~/.mcp_use/ to your .gitignore to avoid committing credentials.

Debugging

Enable verbose logging to troubleshoot authentication:

from mcp_use import set_debug

set_debug(2)  # Shows full OAuth flow, discovery, and token exchange

Security Best Practices

Environment variables - Never hardcode credentials in source code
Token rotation - Rotate long-lived tokens regularly
Minimal scopes - Request only the permissions you need
HTTPS only - All OAuth endpoints use HTTPS (except localhost callbacks)

Get Started

MCP Server

MCP Client

MCP Agents

Development

Authentication Overview

Overview

Choose Your Method

Bearer Token

OAuth 2.1

Custom Auth

Quick Start Examples

Token Storage

Debugging

Security Best Practices

​Overview

​Choose Your Method

Bearer Token

OAuth 2.1

Custom Auth

​Quick Start Examples

​Token Storage

​Debugging

​Security Best Practices

Overview

Choose Your Method

Quick Start Examples

Token Storage

Debugging

Security Best Practices