MCP OAuth Authentication

Connect to OAuth-protected remote MCP servers with PraisonAI’s built-in OAuth 2.1 support.

OAuth implementation is experimental. The current implementation stores placeholder tokens only and real token exchange is not yet implemented. For production use, we recommend using headers: with API key authentication instead.

Status

Capability	Status
OAuth utilities (PKCE, state, callback)	✅ Production ready
Token storage (`~/.praisonai/mcp-auth.json`, 0600 perms)	✅ Production ready
Token exchange via authorisation server	⚠️ Experimental (placeholder)
`praisonai mcp auth` CLI flow	⚠️ Experimental
Wired into `mcp_http_stream.py` for live requests	❌ Not yet

Quick Start

Configure Remote Server

Add a remote MCP server with OAuth to your config. Servers declared in ~/.praisonai/config.yaml (global) or ./.praisonai/config.yaml (project) are automatically picked up by praisonai run:

# ~/.praisonai/config.yaml  (or .praisonai/config.yaml for project-scoped)
mcp:
  servers:
    github:
      type: remote
      url: https://api.github.com/mcp
      oauth:
        client_id: your_client_id
        scopes:
          - repo
          - user

Authenticate

praisonai mcp auth github

This opens your browser for OAuth authorization.

Use the Server

from praisonaiagents import Agent, MCP

agent = Agent(
    instructions="You help with GitHub tasks",
    tools=MCP("https://api.github.com/mcp")
)

CLI Commands

Authenticate

praisonai mcp auth <server-name>

[EXPERIMENTAL] Authenticate with an OAuth-enabled MCP server. WARNING: OAuth implementation is currently experimental and stores placeholder tokens only. Initiates OAuth 2.1 authorization flow:

Opens browser for user authorization
Waits for callback with authorization code
Stores tokens securely in ~/.praisonai/mcp-auth.json

Options:

Option	Default	Description
`--timeout`	`300`	Timeout for OAuth flow in seconds

Logout

praisonai mcp logout <server-name>

Removes stored OAuth credentials for a server. Options:

Option	Description
`--yes`	Skip confirmation prompt

List Servers

praisonai mcp list

Shows all configured servers with their type (local/remote) and status.

Configuration Schema

Remote Server with OAuth

mcp:
  servers:
    my-server:
      type: remote
      url: https://mcp.example.com/mcp
      enabled: true
      timeout: 30000  # milliseconds
      oauth:
        client_id: your_client_id
        client_secret: your_client_secret  # optional
        scopes:
          - read
          - write

Remote Server with API Key

mcp:
  servers:
    tavily:
      type: remote
      url: https://mcp.tavily.com/mcp
      headers:
        Authorization: Bearer ${TAVILY_API_KEY}

Local Server (stdio)

mcp:
  servers:
    filesystem:
      type: local
      command: npx
      args:
        - -y
        - "@anthropic-ai/mcp-server-filesystem"
        - /tmp

Python SDK

Using Auth Storage

from praisonaiagents.mcp import MCPAuthStorage

# Initialize storage
storage = MCPAuthStorage()

# Check if authenticated
entry = storage.get("github")
if entry and entry.get("tokens"):
    print("Authenticated!")
    print(f"Token: {entry['tokens']['access_token'][:20]}...")

# Check token expiration
if storage.is_token_expired("github"):
    print("Token expired, need to re-authenticate")

PKCE Utilities

from praisonaiagents.mcp import (
    generate_state,
    generate_code_verifier,
    generate_code_challenge,
    get_redirect_url
)

# Generate PKCE parameters
state = generate_state()
verifier = generate_code_verifier()
challenge = generate_code_challenge(verifier)

# Get redirect URL for OAuth provider
redirect_url = get_redirect_url()
print(f"Redirect URL: {redirect_url}")
# Output: http://127.0.0.1:19876/mcp/oauth/callback

OAuth Callback Handler

from praisonaiagents.mcp import OAuthCallbackHandler, generate_state
import webbrowser

handler = OAuthCallbackHandler()
state = generate_state()

# Build authorization URL
auth_url = f"https://auth.example.com/authorize?state={state}&..."

# Open browser
webbrowser.open(auth_url)

# Wait for callback (blocks until received or timeout)
try:
    code = handler.wait_for_callback(state, timeout=300)
    print(f"Received authorization code: {code[:20]}...")
except TimeoutError:
    print("OAuth flow timed out")

Token Storage

OAuth tokens are stored in ~/.praisonai/mcp-auth.json with secure file permissions (0600). Storage structure:

{
  "github": {
    "server_url": "https://api.github.com/mcp",
    "tokens": {
      "access_token": "gho_xxx...",
      "refresh_token": "ghr_xxx...",
      "expires_at": 1234567890,
      "scope": "repo user"
    },
    "client_info": {
      "client_id": "xxx",
      "client_secret": "xxx"
    }
  }
}

Security

File permissions: Token storage uses 0600 permissions (owner read/write only)
PKCE: All OAuth flows use PKCE (Proof Key for Code Exchange) for security
State parameter: CSRF protection via random state parameter
URL validation: Tokens are invalidated if server URL changes

Troubleshooting

Issue	Solution
”Server not found”	Add server to config first
”OAuth is only for remote servers”	Use `type: remote` in config
”Authentication timed out”	Increase `--timeout` or check browser
”No credentials stored”	Run `praisonai mcp auth <name>` first

MCP Server - Deploy PraisonAI as MCP server
Remote MCP - Connect to remote MCP servers
MCP Tools - Using MCP tools with agents

​Status

​Quick Start

​CLI Commands

​Authenticate

​Logout

​List Servers

​Configuration Schema

​Remote Server with OAuth

​Remote Server with API Key

​Local Server (stdio)

​Python SDK

​Using Auth Storage

​PKCE Utilities

​OAuth Callback Handler

​Token Storage

​Security

​Troubleshooting

​Related

Status

Quick Start

CLI Commands

Authenticate

Logout

List Servers

Configuration Schema

Remote Server with OAuth

Remote Server with API Key

Local Server (stdio)

Python SDK

Using Auth Storage

PKCE Utilities

OAuth Callback Handler

Token Storage

Security

Troubleshooting

Related