feat(auth): OAuth 2.1 support for remote MCP deployments (Cloud Run, etc.)

[5queezer]

Problem

When deploying the server remotely with --transport streamable-http (e.g. on Google Cloud Run, Hetzner, AWS), there is no authentication layer. Anyone who discovers the URL has full access to the LinkedIn scraping tools.

The current workaround is security-by-obscurity: secret URL paths, IP whitelisting, or a reverse proxy with basic auth. None of these integrate with MCP clients natively.

Meanwhile, the [MCP spec (2025-06-18)](https://modelcontextprotocol.io/docs/tutorials/security/authorization) mandates OAuth 2.1 for remote servers, and clients like claude.ai, Claude Desktop, and Claude Mobile all support OAuth-based custom connectors with Dynamic Client Registration (DCR).

Use Case

As a user deploying this server on Cloud Run alongside other MCP services, I want to add it as a custom connector in claude.ai via Settings → Connectors → Add custom connector — the same way verified connectors work. Currently this only works authless, which means the endpoint is unprotected.

Proposed Solution

Add optional OAuth 2.1 support behind a CLI flag (e.g. --auth oauth), keeping the current authless mode as default for local/stdio usage.

Minimal viable scope

Following the [MCP auth spec](https://modelcontextprotocol.io/docs/tutorials/security/authorization) and [claude.ai connector requirements](https://support.claude.com/en/articles/11503834-building-custom-connectors-via-remote-mcp-servers):

• Protected Resource Metadata at /.well-known/oauth-protected-resource
• Authorization Server Metadata at /.well-known/oauth-authorization-server
• Dynamic Client Registration (DCR) endpoint — required by claude.ai for custom connectors
• Authorization code flow with PKCE — standard OAuth 2.1
• Token endpoint with access token issuance
• 401 → discovery flow on unauthenticated requests
• Bearer token validation on /mcp endpoint

Claude.ai's OAuth callback URL is https://claude.ai/api/mcp/auth_callback.

Implementation options (non-exhaustive)

1. Built-in lightweight OAuth server — embed a minimal OAuth provider in the FastMCP/Uvicorn process. Single-user scenario: one pre-configured user, tokens stored in-memory or SQLite. Keeps the "single Docker container" deployment model.

2. External auth server delegation — support pointing to an external OAuth provider (Keycloak, Auth0, Authelia) via config. Server acts as Resource Server only, validates tokens via introspection or JWKS. More complex but standard.

3. FastMCP native auth — if/when [FastMCP adds OAuth support upstream](https://github.com/modelcontextprotocol/python-sdk), leverage that directly.

What NOT to change

• --transport stdio (local) stays unaffected — no auth needed
• LINKEDIN_COOKIE management is orthogonal and stays as-is
• containerConcurrency: 1 and session serialization unchanged

Alternatives Considered

• Bearer token via header — simpler but not MCP-spec compliant, claude.ai doesn't support static Bearer tokens for custom connectors
• mTLS — not supported by claude.ai connectors
• API key in URL path — current workaround, not discoverable by MCP clients, no standard revocation

Additional Context

• claude.ai supports both the 3/26 and 6/18 MCP auth specs
• claude.ai supports DCR, and as of July 2025 also custom client ID/secret for non-DCR servers
• The server already uses FastMCP + Uvicorn, which provides a good foundation for adding middleware
• Cloud Run, Fly.io, Railway are common deployment targets where this would immediately add value
• Related discussion on MCP auth: [aaronparecki.com/2025/04/03/15/oauth-for-model-context-protocol](https://aaronparecki.com/2025/04/03/15/oauth-for-model-context-protocol)

Checklist (per CONTRIBUTING.md)

Code:

• Add OAuth middleware/endpoints (new module, e.g. auth/)
• Add CLI flags: --auth oauth, --oauth-issuer, etc.
• Integrate with existing create_mcp_server() in server.py

Tests:

• Auth flow unit tests (token issuance, validation, rejection)
• Integration test: unauthenticated request → 401 → discovery
• Existing tools still work with valid token

Docs:

• Update README with remote deployment + OAuth section
• Update docs/docker-hub.md
• Add OAuth config to manifest.json

[stickerdaniel]

Hey, how are you handling the session setup in the remote deployment?

[5queezer]

The LinkedIn browser session is orthogonal to OAuth — OAuth protects the MCP endpoint from unauthorized clients, while the LinkedIn session is baked into the persistent browser profile before the server starts.

For remote deployments the flow is:

1. Locally: create the LinkedIn session via --login (opens a browser, you log into LinkedIn, profile is saved)
2. Deploy: mount or copy ~/.linkedin-mcp/ to the remote server
3. Run: start the server with AUTH=oauth + OAUTH_BASE_URL + OAUTH_PASSWORD — the auth_lifespan validates the profile exists at startup

The implementation plan keeps this unchanged — no modifications to --login, --logout, --status, or any of the session/profile management code. The ### What NOT to change section in the issue description covers this explicitly.