Skip to main content

​
Quick Start

​
OAuth Authentication

For servers that support OAuth, you can use Dynamic Client Registration (automatic) or pre-registered clients: 
// ⚠️ OAuth authentication is not yet supported in the TypeScript library.
// Support is coming soon! If you need this feature now, please open an issue:
// https://github.com/mcp-use/mcp-use

// When supported, the API will look similar to:
/*
import { MCPClient, MCPAgent } from 'mcp-use'
import { ChatOpenAI } from '@langchain/openai'

// Dynamic Client Registration (automatic)
const config = {
    mcpServers: {
        linear: {
            url: 'https://mcp.linear.app/sse',
            // It's not needed to specify auth section
        }
    }
}

// Or with pre-registered client
const configWithAuth = {
    mcpServers: {
        my_server: {
            url: 'https://api.example.com/mcp/',
            auth: {
                clientId: 'your-client-id',
                clientSecret: 'your-client-secret',
            }
        }
    }
}

const client = new MCPClient(config)
const llm = new ChatOpenAI({ model: 'gpt-4o-mini', temperature: 0 })
const agent = new MCPAgent({ llm, client })

const response = await agent.run('Your query here')
console.log(response)
*/

​
Bearer Token Authentication

For servers requiring API keys: 
// ⚠️ Bearer token authentication is not yet supported in the TypeScript library.
// Support is coming soon! If you need this feature now, please open an issue:
// https://github.com/mcp-use/mcp-use

// When supported, the API will look similar to:
/*
const config = {
    mcpServers: {
        api: {
            url: 'https://api.example.com/mcp/sse',
            auth: 'sk-your-api-key-here'
        }
    }
}
*/

​
Custom Port Configuration

You can specify a custom port for OAuth callbacks to avoid conflicts: 
// ⚠️ Not yet supported - see OAuth authentication above

​
Authentication Methods

​
1. OAuth 2.0 Authentication

OAuth 2.0 is the most common authentication method for MCP servers. mcp-use supports:
  • Dynamic Client Registration (DCR) - Automatic client registration
  • Pre-registered Clients - Using existing OAuth applications
  • Custom OAuth Providers - With explicit metadata

​
Dynamic Client Registration

For servers that support DCR, you don’t need to register a client manually:

​
Pre-registered OAuth Client

For servers requiring manual client registration:

​
OAuth Provider with Metadata

For servers with known OAuth endpoints, provide metadata upfront:

​
2. Bearer Token Authentication

For servers requiring simple API keys or bearer tokens:

​
3. Custom Authentication

For servers requiring custom authentication methods:

​
4. No Authentication

For public servers or servers without authentication:

​
Complete Examples

​
GitHub MCP Server Example

The GitHub MCP server requires OAuth authentication. You’ll need to create a GitHub OAuth App first:
  1. Create a GitHub OAuth App:
    • Go to GitHub OAuth Apps
    • Set Application name: your-app-name
    • Set Homepage URL: http://localhost:8080 (or your custom port)
    • Set Authorization callback URL: http://localhost:8080/callback (or your custom port)
    • Click “Register application”
    • Copy your Client ID and Client Secret
  2. Configure mcp-use:

​
Multi-Server Configuration

You can mix different authentication methods across servers:

​
OAuth Flow Process

When OAuth authentication is required:
  1. Browser Opens: Your default browser opens to the authorization page
  2. Grant Access: Review and approve the requested permissions
  3. Automatic Redirect: You’re redirected to a local callback URL
  4. Token Storage: Access tokens are stored securely in ~/.mcp_use/tokens/

​
Token Storage

Authentication data is stored securely:
  • Access Tokens: ~/.mcp_use/tokens/{server_domain}.json
  • Client Registrations: ~/.mcp_use/tokens/registrations/{server_domain}_registration.json

​
Configuration Options

​
OAuth Configuration Parameters

ParameterTypeRequiredDescription
client_idstringNo*OAuth client ID (required if not using DCR)
client_secretstringNoOAuth client secret (required if not using DCR)
scopestringNoOAuth scopes to request
callback_portintegerNoPort for OAuth callback (default: 8080)
oauth_providerobjectNoOAuth 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

​
Troubleshooting

​
Common Issues

​
OAuth Discovery Fails

If a server doesn’t support OAuth discovery:
  • Provide an oauth_provider with metadata
  • Use a pre-registered client_id
  • Check if the server requires different authentication

​
”Invalid redirect URI” Error

Solutions:
  • Use Dynamic Client Registration (omit client_id)
  • Register your app with supported redirect URIs
  • Check if your provider supports wildcard redirect URIs
  • Ensure callback URL matches your OAuth app configuration

​
Port Already in Use

If you get a port conflict error:

​
GitHub OAuth Issues

For GitHub specifically:
  • Ensure your OAuth app callback URL matches: http://localhost:8080/callback (or your custom port)
  • Use correct scopes: repo, read:user, etc.
  • Check that your GitHub OAuth app is properly configured

​
Debugging

Enable debug logging to see detailed authentication flow:

​
Security Best Practices

  • Token Storage: Tokens are stored with restricted permissions
  • Version Control: Never commit authentication files to version control
  • CSRF Protection: OAuth flow uses state parameter for CSRF protection
  • Localhost Callbacks: All callbacks use localhost (127.0.0.1) for security
  • Isolation: Each server’s authentication is isolated
  • Environment Variables: Use environment variables for sensitive data:

​
Example Servers that support OAuth

​
OAuth with DCR Support

  • Linear: https://mcp.linear.app/sse
  • Asana: https://mcp.asana.com/sse
  • Atlassian: https://mcp.atlassian.com/v1/sse

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