OAuth2 Authentication - Grounded Docs MCP Server

Overview

The Docs MCP Server supports optional OAuth2 authentication for HTTP endpoints, providing enterprise-grade security while maintaining a frictionless local development experience. Authentication is disabled by default and uses a binary authentication model for maximum compatibility with OAuth2 providers.

Important: The Docs MCP Server is an OAuth2 protected resource, not an OAuth2 authorization server. It relies on external OAuth2 providers (such as Auth0, Clerk, Keycloak, or Azure AD) for authentication and authorization. The server validates JWT tokens issued by these providers but does not issue tokens itself.

Security Scope

OAuth2 authentication only protects MCP endpoints (/mcp, /sse). The tRPC API endpoints (/api) used for internal pipeline communication are not protected by OAuth2 authentication.

Security Notice: When deploying workers in distributed environments, ensure that tRPC API endpoints are secured at the network level (e.g., within a private VPC, Kubernetes cluster network, or through Docker Compose internal networking). These endpoints should never be exposed to the public internet without additional security measures.

Protected Endpoints

MCP endpoints - Protected by OAuth2 when --auth-enabled is used
tRPC API endpoints - Must be secured through network-level controls
Web interface - Can be protected by OAuth2 when enabled on the default command

Architecture

The authentication system uses a binary authentication model with OAuth2 proxy support, providing secure access control while maintaining compatibility with any RFC 6749 compliant OAuth2 provider.

Binary Authentication Model

The system implements a simplified binary access control model:

Authenticated Users - Full access to all MCP tools and endpoints
Unauthenticated Users - No access (401 responses)

This approach eliminates complex scope management while maintaining security, ensuring broad compatibility with OAuth2 providers that may not support custom scopes for DCR workflows.

OAuth2 Proxy with DCR Support

The server includes a built-in OAuth2 proxy that enables seamless integration with MCP clients:

Dynamic Client Registration (DCR) - RFC 7591 compliant automatic client registration
Resource Parameter Support - RFC 8707 compliant multi-transport resource identification
Multi-Transport Detection - Automatic resource URL detection for SSE and HTTP transports
Standard OAuth Flows - Authorization Code, Client Credentials, and refresh token support
Smart Discovery - Uses OAuth2 authorization server discovery (RFC 8414) for comprehensive endpoint detection including DCR and JWKS

Authentication Flow

Configuration

Authentication settings live in appConfig.auth and follow the unified precedence: defaults → docs-mcp.config.yaml (or DOCS_MCP_CONFIG) → legacy envs → generic env DOCS_MCP_<KEY> → CLI flags for the current run.

Setup Steps

Set up your OAuth2 provider (Auth0, Clerk, Keycloak, etc.) with standard OAuth identity scopes
Configure the Docs MCP Server to validate tokens from that provider using the settings below

Configuration Options

Option	CLI Flag	Environment Variable	Description
Enable Auth	`--auth-enabled`	`DOCS_MCP_AUTH_ENABLED`	Enable OAuth2 token validation
Issuer URL	`--auth-issuer-url`	`DOCS_MCP_AUTH_ISSUER_URL`	OAuth2 discovery endpoint of your external provider
Audience	`--auth-audience`	`DOCS_MCP_AUTH_AUDIENCE`	JWT audience claim (identifies this protected resource)

# Configure Docs MCP Server to validate tokens from your OAuth2/OIDC provider
npx docs-mcp-server \
  --auth-enabled \
  --auth-issuer-url "https://auth.your-domain.com" \
  --auth-audience "https://mcp.your-domain.com"

OAuth2 Provider Setup

Prerequisite: You must first set up an OAuth2/OIDC provider separately. The following examples show how to configure popular providers to work with the Docs MCP Server.

Supported Providers

The Docs MCP Server works with any RFC 6749 compliant OAuth2 provider. Here are configuration examples for popular providers:

npx docs-mcp-server \
  --auth-enabled \
  --auth-issuer-url "https://your-tenant.auth0.com" \
  --auth-audience "https://mcp.your-domain.com"

JWT Configuration

For providers that use JWT tokens, ensure your JWT template/claims include the resource ID as the audience claim:

Clerk JWT Template Example

{
  "aud": "https://mcp.your-domain.com",
  "sub": "{{user.id}}",
  "email": "{{user.primaryEmailAddress.emailAddress}}",
  "name": "{{user.fullName}}"
}

Resource ID Requirements

Must be a valid URI (URL or URN)
URL examples: https://mcp.your-domain.com, http://localhost:6280 (dev only)
URN examples: urn:docs-mcp-server:api, urn:company:service
Used as the JWT audience claim for validation
Should be unique and not conflict with your actual server URL

OAuth2 Endpoints

The server exposes OAuth2 proxy endpoints for Dynamic Client Registration and standard OAuth flows:

/.well-known/oauth-authorization-server - OAuth2 discovery metadata
/oauth/register - Dynamic Client Registration (DCR) endpoint
/oauth/authorize - Authorization endpoint (proxied to provider)
/oauth/token - Token endpoint (proxied to provider)
/oauth/revoke - Token revocation (proxied to provider)

Protected Resource Metadata

The server exposes RFC 9728 compliant metadata at /.well-known/oauth-protected-resource:

{
  "resource": "https://mcp.your-domain.com",
  "authorization_servers": ["https://your-provider.example.com"],
  "scopes_supported": ["openid", "profile", "email"],
  "resource_name": "Documentation MCP Server",
  "resource_documentation": "https://github.com/arabold/docs-mcp-server#readme",
  "bearer_methods_supported": ["header"]
}

MCP Client Integration

MCP clients can authenticate using standard OAuth2 flows with DCR support:

Discovery: Fetch /.well-known/oauth-authorization-server for OAuth2 metadata
Registration: Use DCR endpoint to automatically register client credentials
Authentication: Obtain JWT token using OAuth2 Authorization Code flow
API Access: Include Authorization: Bearer <token> header in MCP requests

Dynamic Client Registration: The Docs MCP Server supports RFC 7591 compliant DCR, enabling MCP clients like VS Code to automatically register and obtain authorization without manual client configuration. The DCR workflow is proxied to your OAuth2 provider with resource parameter support for multi-transport scenarios.

Example Client Request

// Obtain token from your OAuth2 provider
const token = await getAccessToken();

// Use token in requests
const response = await fetch("http://localhost:6280/mcp", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    method: "search_docs",
    params: { library: "react", query: "hooks" },
    id: 1,
  }),
});

Binary Access Control

All authenticated users receive full access to all MCP tools and endpoints. The system does not implement granular permissions or role-based access control.

Available MCP Tools

All tools are available to authenticated users:

Documentation Operations

list_libraries - List indexed documentation libraries
search_docs - Search within documentation
fetch_url - Retrieve content from URLs
find_version - Find library version information

Content Management

scrape_docs - Index new documentation content
remove_docs - Remove indexed documentation

Job Management

get_job_info - View job status and details
list_jobs - List processing jobs
cancel_job - Cancel running jobs
clear_completed_jobs - Clean up completed jobs

Security Features

JWT Validation

Signature Verification: Cryptographic validation using provider’s public keys from JWKS endpoint
Claim Validation: Issuer, audience, and expiration time verification
Binary Authentication: Simple authenticated/unauthenticated access control

Error Handling

401 Unauthorized: Missing, invalid, or expired authentication token
WWW-Authenticate Header: RFC 6750 compliant challenge responses
Detailed Error Messages: Clear feedback for authentication failures

Fail-Safe Design

Disabled by Default: No authentication required for local development
Graceful Degradation: Invalid configuration logs errors but doesn’t crash
Provider Independence: Works with any RFC 6749 compliant OAuth2 provider

Troubleshooting

Common Issues

401 Unauthorized Error

Check token is included in Authorization header
Verify token hasn’t expired
Confirm provider URL and resource ID configuration
Ensure resource ID matches the JWT audience claim

DCR Registration Failures

Verify OAuth2 provider supports Dynamic Client Registration
Check provider DCR endpoint is accessible
Ensure provider allows the requested redirect URIs
Review provider logs for DCR-specific errors

500 Internal Server Error

Check provider discovery endpoint is accessible
Verify provider URL configuration
Review server logs for detailed error messages
Ensure provider JWKS endpoint is reachable

Debug Logging

Enable debug logging to troubleshoot authentication issues:

DEBUG=mcp:auth npx docs-mcp-server --auth-enabled --auth-issuer-url "..."

Security Considerations

Token Security

Use HTTPS in production environments
Implement proper token storage in clients
Consider token refresh strategies for long-running operations
Monitor token expiration and handle renewal

Network Security

Deploy behind TLS termination
Consider API rate limiting
Implement proper CORS policies for web clients
Use secure OAuth2 flows (Authorization Code with PKCE)

Access Control

All authenticated users receive full access to all endpoints
Consider additional authorization layers if granular permissions are required
Monitor user activity and implement audit logging
Regularly review OAuth2 provider user access and permissions

Usage Examples

# Start server without authentication
npx docs-mcp-server --port 6280

Getting Started

Setup

Guides

Architecture

Infrastructure

​Overview

​Security Scope

​Protected Endpoints

​Architecture

​Binary Authentication Model

​OAuth2 Proxy with DCR Support

​Authentication Flow

​Configuration

​Setup Steps

​Configuration Options

​OAuth2 Provider Setup

​Supported Providers

​JWT Configuration

​Resource ID Requirements

​OAuth2 Endpoints

​Protected Resource Metadata

​MCP Client Integration

​Example Client Request

​Binary Access Control

​Available MCP Tools

​Documentation Operations

​Content Management

​Job Management

​Security Features

​JWT Validation

​Error Handling

​Fail-Safe Design

​Troubleshooting

​Common Issues

​Debug Logging

​Security Considerations

​Token Security

​Network Security

​Access Control

​Usage Examples

Build docs developers (and LLMs) love

Overview

Security Scope

Protected Endpoints

Architecture

Binary Authentication Model

OAuth2 Proxy with DCR Support

Authentication Flow

Configuration

Setup Steps

Configuration Options

OAuth2 Provider Setup

Supported Providers

JWT Configuration

Resource ID Requirements

OAuth2 Endpoints

Protected Resource Metadata

MCP Client Integration

Example Client Request

Binary Access Control

Available MCP Tools

Documentation Operations

Content Management

Job Management

Security Features

JWT Validation

Error Handling

Fail-Safe Design

Troubleshooting

Common Issues

Debug Logging

Security Considerations

Token Security

Network Security

Access Control

Usage Examples