Complete Guide to QuickMCP Authentication Methods

Securing your MCP servers is critical. QuickMCP supports five authentication methods, each designed for different use cases. Let me show you how to use each one effectively.

Why Authentication Matters in MCP Servers

When you expose APIs through MCP, you're giving AI assistants access to potentially sensitive operations. Proper authentication ensures only authorized requests reach your backend.

1. API Key Authentication

The simplest and most common method. Perfect for internal tools and APIs that use header or query parameter keys.

Configuration

var authenticator = new ApiKeyAuthenticator(
    apiKey: "your-api-key",
    paramName: "X-API-Key",
    location: "header"  // or "query"
);

CLI Usage

quickmcp build config \
  --spec-url https://api.example.com/swagger.json \
  --auth apikey \
  --output-path ./config.json

Then edit the config:

{
  "authentication": {
    "type": "ApiKey",
    "apiKey": "${API_KEY}",
    "paramName": "X-API-Key",
    "location": "header"
  }
}

Best For

• Internal APIs
• Simple third-party services
• Development and testing

2. Basic Authentication

Uses Base64-encoded username and password. Still widely used in legacy systems.

Configuration

var authenticator = new BasicAuthenticator(
    username: "admin",
    password: "secure-password"
);

CLI Configuration

{
  "authentication": {
    "type": "Basic",
    "username": "${USERNAME}",
    "password": "${PASSWORD}"
  }
}

Security Note

Always use environment variables, never hardcode credentials:

export USERNAME="admin"
export PASSWORD="secure-password"
quickmcp serve --config-path ./config.json

Best For

• Legacy enterprise systems
• Internal tools with simple auth
• Development environments

3. Bearer Token Authentication

Modern and clean. Perfect for JWT tokens and OAuth access tokens.

Configuration

var authenticator = new BearerTokenAuthenticator(
    token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
);

CLI Configuration

{
  "authentication": {
    "type": "Bearer",
    "token": "${BEARER_TOKEN}"
  }
}

Real Example: GitHub API

export BEARER_TOKEN="ghp_your_personal_access_token"
quickmcp serve --config-path ./github-config.json

Best For

• Modern REST APIs (GitHub, Stripe, Twilio)
• JWT-based authentication
• OAuth 2.0 access tokens

4. OAuth 2.0 Client Credentials

Enterprise-grade authentication with automatic token refresh.

Configuration

var authenticator = new OAuth2Authenticator(
    tokenUrl: "https://auth.example.com/oauth/token",
    clientId: "your-client-id",
    clientSecret: "your-client-secret",
    scopes: new[] { "read", "write" }
);

CLI Configuration

{
  "authentication": {
    "type": "OAuth2",
    "tokenUrl": "https://auth.example.com/oauth/token",
    "clientId": "${OAUTH_CLIENT_ID}",
    "clientSecret": "${OAUTH_CLIENT_SECRET}",
    "scopes": ["read", "write"]
  }
}

What QuickMCP Handles Automatically

• Token acquisition
• Token refresh when expired
• Scope management
• Error handling

Best For

• Azure AD integrated APIs
• Auth0 protected services
• Enterprise SaaS platforms
• Any OAuth 2.0 compliant API

5. Custom Header Authentication

For proprietary authentication schemes that don't fit standard patterns.

Configuration

var authenticator = new CustomHeaderAuthenticator(
    headerName: "X-Custom-Auth",
    headerValue: "custom-magic-value"
);

CLI Configuration

{
  "authentication": {
    "type": "CustomHeader",
    "headerName": "X-Custom-Auth",
    "headerValue": "${CUSTOM_AUTH_VALUE}"
  }
}

Best For

• Custom internal APIs
• Proprietary authentication schemes
• Legacy systems with non-standard auth

Security Best Practices

Never Hardcode Credentials

Bad:

{
  "apiKey": "sk-proj-actual-secret-key"
}

Good:

{
  "apiKey": "${API_KEY}"
}

Use Environment Variables

# Set once
export API_KEY="your-secret-key"
export OAUTH_CLIENT_SECRET="your-secret"

# Use everywhere
quickmcp serve --config-path ./config.json

Rotate Credentials Regularly

Set reminders to rotate API keys and secrets every 90 days.

Apply Least Privilege

Only request the permissions (scopes) you actually need.

Choosing the Right Method

Common Issues

Issue: OAuth Token Expired

QuickMCP handles this automatically. Check logs if refresh fails:

quickmcp serve --config-path ./config.json --logging

Issue: API Key Not Recognized

Verify parameter name and location:

• Header: Usually X-API-Key, Authorization, or custom
• Query: Usually api_key, key, or token

Issue: Basic Auth Fails

Ensure credentials don't have special characters that need encoding.

Testing Authentication

Use the --logging flag to see authentication headers:

quickmcp serve --config-path ./config.json --logging

You'll see output like:

[INFO] Adding authentication header: X-API-Key
[INFO] Request to: https://api.example.com/endpoint

Next Steps

• Check out CLI Commands Guide for more options
• Learn about Path Filtering for security
• Explore Configuration Methods

Authentication is the foundation of secure MCP servers. Choose the right method for your API, use environment variables, and you're good to go.