claude-code/plugins/plugin-dev/skills/mcp-integration/references/authentication.md

MCP Authentication Patterns

Complete guide to authentication methods for MCP servers in Claude Code plugins.

Overview

MCP servers support multiple authentication methods depending on the server type and service requirements. Choose the method that best matches your use case and security requirements.

OAuth (Automatic)

How It Works

Claude Code automatically handles the complete OAuth 2.0 flow for SSE and HTTP servers:

1. User attempts to use MCP tool
2. Claude Code detects authentication needed
3. Opens browser for OAuth consent
4. User authorizes in browser
5. Tokens stored securely by Claude Code
6. Automatic token refresh

Configuration

{
  "service": {
    "type": "sse",
    "url": "https://mcp.example.com/sse"
  }
}

No additional auth configuration needed! Claude Code handles everything.

Supported Services

Known OAuth-enabled MCP servers:

• Asana: https://mcp.asana.com/sse
• GitHub (when available)
• Google services (when available)
• Custom OAuth servers

OAuth Scopes

OAuth scopes are determined by the MCP server. Users see required scopes during the consent flow.

Document required scopes in your README:

## Authentication

This plugin requires the following Asana permissions:
- Read tasks and projects
- Create and update tasks
- Access workspace data

Token Storage

Tokens are stored securely by Claude Code:

• Not accessible to plugins
• Encrypted at rest
• Automatic refresh
• Cleared on sign-out

Troubleshooting OAuth

Authentication loop:

• Clear cached tokens (sign out and sign in)
• Check OAuth redirect URLs
• Verify server OAuth configuration

Scope issues:

• User may need to re-authorize for new scopes
• Check server documentation for required scopes

Token expiration:

• Claude Code auto-refreshes
• If refresh fails, prompts re-authentication

Token-Based Authentication

Bearer Tokens

Most common for HTTP and WebSocket servers.

Configuration:

{
  "api": {
    "type": "http",
    "url": "https://api.example.com/mcp",
    "headers": {
      "Authorization": "Bearer ${API_TOKEN}"
    }
  }
}

Environment variable:

export API_TOKEN="your-secret-token-here"

API Keys

Alternative to Bearer tokens, often in custom headers.

Configuration:

{
  "api": {
    "type": "http",
    "url": "https://api.example.com/mcp",
    "headers": {
      "X-API-Key": "${API_KEY}",
      "X-API-Secret": "${API_SECRET}"
    }
  }
}

Custom Headers

Services may use custom authentication headers.

Configuration:

{
  "service": {
    "type": "sse",
    "url": "https://mcp.example.com/sse",
    "headers": {
      "X-Auth-Token": "${AUTH_TOKEN}",
      "X-User-ID": "${USER_ID}",
      "X-Tenant-ID": "${TENANT_ID}"
    }
  }
}

Documenting Token Requirements

Always document in your README:

## Setup

### Required Environment Variables

Set these environment variables before using the plugin:

\`\`\`bash
export API_TOKEN="your-token-here"
export API_SECRET="your-secret-here"
\`\`\`

### Obtaining Tokens

1. Visit https://api.example.com/tokens
2. Create a new API token
3. Copy the token and secret
4. Set environment variables as shown above

### Token Permissions

The API token needs the following permissions:
- Read access to resources
- Write access for creating items
- Delete access (optional, for cleanup operations)
\`\`\`

Environment Variable Authentication (stdio)

Passing Credentials to Server

For stdio servers, pass credentials via environment variables:

{
  "database": {
    "command": "python",
    "args": ["-m", "mcp_server_db"],
    "env": {
      "DATABASE_URL": "${DATABASE_URL}",
      "DB_USER": "${DB_USER}",
      "DB_PASSWORD": "${DB_PASSWORD}"
    }
  }
}

User Environment Variables

# User sets these in their shell
export DATABASE_URL="postgresql://localhost/mydb"
export DB_USER="myuser"
export DB_PASSWORD="mypassword"

Documentation Template

## Database Configuration

Set these environment variables:

\`\`\`bash
export DATABASE_URL="postgresql://host:port/database"
export DB_USER="username"
export DB_PASSWORD="password"
\`\`\`

Or create a `.env` file (add to `.gitignore`):

\`\`\`
DATABASE_URL=postgresql://localhost:5432/mydb
DB_USER=myuser
DB_PASSWORD=mypassword
\`\`\`

Load with: \`source .env\` or \`export $(cat .env | xargs)\`
\`\`\`

Dynamic Headers

Headers Helper Script

For tokens that change or expire, use a helper script:

{
  "api": {
    "type": "sse",
    "url": "https://api.example.com",
    "headersHelper": "${CLAUDE_PLUGIN_ROOT}/scripts/get-headers.sh"
  }
}

Script (get-headers.sh):

#!/bin/bash
# Generate dynamic authentication headers

# Fetch fresh token
TOKEN=$(get-fresh-token-from-somewhere)

# Output JSON headers
cat <<EOF
{
  "Authorization": "Bearer $TOKEN",
  "X-Timestamp": "$(date -Iseconds)"
}
EOF

Use Cases for Dynamic Headers

• Short-lived tokens that need refresh
• Tokens with HMAC signatures
• Time-based authentication
• Dynamic tenant/workspace selection

TTL Configuration

By default, dynamically generated API keys are cached for 5 minutes. Configure the TTL with:

export CLAUDE_CODE_API_KEY_HELPER_TTL_MS=300000  # 5 minutes (default)

Writing Robust Helper Scripts

Helper scripts can cause issues if they hang or fail repeatedly. Follow these best practices to prevent infinite retry loops and connection hangs:

1. Always set timeouts on network operations:

#!/bin/bash
# get-token.sh - Robust token fetcher

# Set a timeout for the entire script
TIMEOUT_SECONDS=10

# Use timeout for network calls
TOKEN=$(timeout ${TIMEOUT_SECONDS}s curl -s --max-time ${TIMEOUT_SECONDS} \
  "https://auth.example.com/token" 2>/dev/null)

if [ -z "$TOKEN" ] || [ "$TOKEN" = "null" ]; then
  # Exit with error - don't output invalid JSON
  echo "Failed to fetch token" >&2
  exit 1
fi

echo "{\"Authorization\": \"Bearer $TOKEN\"}"

2. Handle VPN/network dependency failures:

#!/bin/bash
# get-headers.sh - VPN-aware token fetcher

# Quick connectivity check before attempting auth
if ! timeout 2s ping -c 1 vpn-dependent-service.internal >/dev/null 2>&1; then
  echo "VPN not connected or service unreachable" >&2
  exit 1
fi

# Proceed with token fetch (with timeout)
TOKEN=$(timeout 10s get-token-from-vpn-service)

if [ $? -ne 0 ] || [ -z "$TOKEN" ]; then
  echo "Token fetch failed" >&2
  exit 1
fi

echo "{\"Authorization\": \"Bearer $TOKEN\"}"

3. Cache tokens locally to reduce network calls:

#!/bin/bash
# get-headers-cached.sh - Token fetcher with local caching

CACHE_FILE="${HOME}/.cache/my-api-token"
CACHE_MAX_AGE=240  # seconds (refresh before 5min TTL)

# Check cache validity
if [ -f "$CACHE_FILE" ]; then
  CACHE_AGE=$(($(date +%s) - $(stat -c %Y "$CACHE_FILE" 2>/dev/null || stat -f %m "$CACHE_FILE")))
  if [ "$CACHE_AGE" -lt "$CACHE_MAX_AGE" ]; then
    cat "$CACHE_FILE"
    exit 0
  fi
fi

# Fetch new token with timeout
TOKEN=$(timeout 10s fetch-new-token 2>/dev/null)

if [ -z "$TOKEN" ]; then
  # If fetch fails, try to use expired cache as fallback
  if [ -f "$CACHE_FILE" ]; then
    echo "Warning: Using expired cached token" >&2
    cat "$CACHE_FILE"
    exit 0
  fi
  echo "Failed to fetch token and no cache available" >&2
  exit 1
fi

# Update cache
mkdir -p "$(dirname "$CACHE_FILE")"
echo "{\"Authorization\": \"Bearer $TOKEN\"}" > "$CACHE_FILE"
cat "$CACHE_FILE"

4. Fail fast with clear error messages:

#!/bin/bash
set -e  # Exit on any error

# Check prerequisites before attempting network calls
if [ -z "$API_SECRET" ]; then
  echo "API_SECRET environment variable not set" >&2
  exit 1
fi

# Use short timeouts to fail fast
TOKEN=$(timeout 5s curl -sf --max-time 5 \
  -H "X-Secret: $API_SECRET" \
  "https://auth.example.com/token") || {
  echo "Token request failed or timed out" >&2
  exit 1
}

echo "{\"Authorization\": \"Bearer $TOKEN\"}"

Troubleshooting Helper Scripts

Infinite retry loop / hanging:

• Add timeouts to all network operations
• Use set -e to exit on errors
• Check VPN/network connectivity before making requests
• Ensure script outputs valid JSON or exits with error code

Script takes too long:

• Use timeout command wrapper
• Set --max-time on curl requests
• Consider caching tokens locally
• Reduce TTL if tokens refresh too slowly

VPN-dependent helpers failing:

• Add connectivity check at start of script
• Implement graceful degradation with cached tokens
• Log clear error messages to stderr

Security Best Practices

DO

✅ Use environment variables:

{
  "headers": {
    "Authorization": "Bearer ${API_TOKEN}"
  }
}

✅ Document required variables in README

✅ Use HTTPS/WSS always

✅ Implement token rotation

✅ Store tokens securely (env vars, not files)

✅ Let OAuth handle authentication when available

DON'T

❌ Hardcode tokens:

{
  "headers": {
    "Authorization": "Bearer sk-abc123..."  // NEVER!
  }
}

❌ Commit tokens to git

❌ Share tokens in documentation

❌ Use HTTP instead of HTTPS

❌ Store tokens in plugin files

❌ Log tokens or sensitive headers

Multi-Tenancy Patterns

Workspace/Tenant Selection

Via environment variable:

{
  "api": {
    "type": "http",
    "url": "https://api.example.com/mcp",
    "headers": {
      "Authorization": "Bearer ${API_TOKEN}",
      "X-Workspace-ID": "${WORKSPACE_ID}"
    }
  }
}

Via URL:

{
  "api": {
    "type": "http",
    "url": "https://${TENANT_ID}.api.example.com/mcp"
  }
}

Per-User Configuration

Users set their own workspace:

export WORKSPACE_ID="my-workspace-123"
export TENANT_ID="my-company"

Authentication Troubleshooting

Common Issues

401 Unauthorized:

• Check token is set correctly
• Verify token hasn't expired
• Check token has required permissions
• Ensure header format is correct

403 Forbidden:

• Token valid but lacks permissions
• Check scope/permissions
• Verify workspace/tenant ID
• May need admin approval

Token not found:

# Check environment variable is set
echo $API_TOKEN

# If empty, set it
export API_TOKEN="your-token"

Token in wrong format:

// Correct
"Authorization": "Bearer sk-abc123"

// Wrong
"Authorization": "sk-abc123"

Debugging Authentication

Enable debug mode:

claude --debug

Look for:

• Authentication header values (sanitized)
• OAuth flow progress
• Token refresh attempts
• Authentication errors

Test authentication separately:

# Test HTTP endpoint
curl -H "Authorization: Bearer $API_TOKEN" \
     https://api.example.com/mcp/health

# Should return 200 OK

Migration Patterns

From Hardcoded to Environment Variables

Before:

{
  "headers": {
    "Authorization": "Bearer sk-hardcoded-token"
  }
}

After:

{
  "headers": {
    "Authorization": "Bearer ${API_TOKEN}"
  }
}

Migration steps:

1. Add environment variable to plugin README
2. Update configuration to use ${VAR}
3. Test with variable set
4. Remove hardcoded value
5. Commit changes

From Basic Auth to OAuth

Before:

{
  "headers": {
    "Authorization": "Basic ${BASE64_CREDENTIALS}"
  }
}

After:

{
  "type": "sse",
  "url": "https://mcp.example.com/sse"
}

Benefits:

• Better security
• No credential management
• Automatic token refresh
• Scoped permissions

Advanced Authentication

Mutual TLS (mTLS)

Some enterprise services require client certificates.

Not directly supported in MCP configuration.

Workaround: Wrap in stdio server that handles mTLS:

{
  "secure-api": {
    "command": "${CLAUDE_PLUGIN_ROOT}/servers/mtls-wrapper",
    "args": ["--cert", "${CLIENT_CERT}", "--key", "${CLIENT_KEY}"],
    "env": {
      "API_URL": "https://secure.example.com"
    }
  }
}

JWT Tokens

Generate JWT tokens dynamically with headers helper:

#!/bin/bash
# generate-jwt.sh

# Generate JWT (using library or API call)
JWT=$(generate-jwt-token)

echo "{\"Authorization\": \"Bearer $JWT\"}"

{
  "headersHelper": "${CLAUDE_PLUGIN_ROOT}/scripts/generate-jwt.sh"
}

HMAC Signatures

For APIs requiring request signing:

#!/bin/bash
# generate-hmac.sh

TIMESTAMP=$(date -Iseconds)
SIGNATURE=$(echo -n "$TIMESTAMP" | openssl dgst -sha256 -hmac "$SECRET_KEY" | cut -d' ' -f2)

cat <<EOF
{
  "X-Timestamp": "$TIMESTAMP",
  "X-Signature": "$SIGNATURE",
  "X-API-Key": "$API_KEY"
}
EOF

Best Practices Summary

For Plugin Developers

1. Prefer OAuth when service supports it
2. Use environment variables for tokens
3. Document all required variables in README
4. Provide setup instructions with examples
5. Never commit credentials
6. Use HTTPS/WSS only
7. Test authentication thoroughly

For Plugin Users

1. Set environment variables before using plugin
2. Keep tokens secure and private
3. Rotate tokens regularly
4. Use different tokens for dev/prod
5. Don't commit .env files to git
6. Review OAuth scopes before authorizing

Conclusion

Choose the authentication method that matches your MCP server's requirements:

• OAuth for cloud services (easiest for users)
• Bearer tokens for API services
• Environment variables for stdio servers
• Dynamic headers for complex auth flows

Always prioritize security and provide clear setup documentation for users.