ai/doc/m_c_p_client_authentication_modes.md

Mode A: Platform Harness → Hosted Container (internal) Auth: mTLS + platform-signed user claim Network: k8s internal, never hits the internet

Mode B: Platform Harness → External User Container (remote) Auth: OAuth2 token issued by your platform Network: public internet, TLS required

Mode C: Third-party MCP Client → External User Container (standalone) Auth: User-managed API key or local-only (no network) Network: localhost or user's own network

┌──────────────────────────────────────────────────────────┐ │ Platform (Postgres) │ │ │ │ users │ │ ├── id, email, password_hash, plan_tier │ │ │ │ │ containers │ │ ├── user_id │ │ ├── type: "hosted" | "external" │ │ ├── mcp_endpoint: "internal-svc:3100" | "https://..." │ │ ├── auth_method: "mtls" | "platform_token" | "api_key" │ │ └── public_key_fingerprint (for pinning external certs) │ │ │ │ api_tokens │ │ ├── user_id │ │ ├── token_hash │ │ ├── scopes: ["mcp:tools", "mcp:resources", "data:read"] │ │ ├── expires_at │ │ └── issued_for: "platform_harness" | "user_direct" │ │ │ └──────────────────────────────────────────────────────────┘

Mode A

Harness ──mTLS──▶ k8s Service ──▶ User Container MCP Validates: source is platform namespace Extracts: user_id from forwarded header

Mode B

Registration flow (one-time):

1. User provides their MCP endpoint URL in platform settings
2. Platform generates a scoped token (JWT, short-lived, auto-refreshed)
3. User configures their MCP server to accept tokens signed by your platform
4. Platform stores the endpoint + auth method

Runtime: ┌──────────┐ HTTPS + Bearer token ┌────────────────────┐ │ Harness │ ─────────────────────────▶ │ External MCP Server│ │ │ Authorization: │ │ │ │ Bearer <platform_jwt> │ Validates: │ │ │ │ - JWT signature │ │ │ │ (your public │ │ │ │ key, JWKS) │ │ │ │ - user_id claim │ │ │ │ matches self │ │ │ │ - not expired │ └──────────┘ └────────────────────┘

Mode C

# openclaw/config.yaml
auth:
  # For local-only use (Claude Desktop, Cursor, etc via stdio)
  mode: "local"          # no network auth needed

  # OR for remote access
  mode: "token"
  tokens:
    - name: "my-laptop"
      hash: "sha256:..."  # generated by `openclaw token create`

  # OR for platform integration
  mode: "platform"
  platform_jwks_url: "https://api.openclaw.io/.well-known/jwks.json"
  expected_user_id: "user_abc123"