Kalpana MCP Documentation

How AI agents authenticate with Kalpana via OAuth 2.0, PKCE S256, and Client ID Metadata Documents.

The Kalpana MCP gateway uses standard OAuth 2.0 with Authorization Code Flow and PKCE S256 (RFC 7636). It does not use static master API keys in multi-user environments; instead, each agent request carries the authenticating user's short-lived bearer token.

Authentication Architecture

sequenceDiagram
    participant Agent as MCP Client (e.g. ChatGPT)
    participant Worker as MCP Gateway (mcp.kalpana.one)
    participant Web as Kalpana Web App (app.kalpana.one)
    participant User as End User

    Agent->>Worker: GET /.well-known/oauth-authorization-server
    Worker-->>Agent: OAuth Metadata (CIMD, PKCE endpoints)
    Agent->>Worker: GET /oauth/authorize (code_challenge)
    Worker->>User: Redirect to Kalpana Login & Consent
    User->>Web: Approves Workspace Scopes
    Web-->>Agent: Authorization Code
    Agent->>Worker: POST /oauth/token (code_verifier)
    Worker->>Web: Validates Code & Returns Opaque Tokens
    Worker-->>Agent: Access Token + Rotating Refresh Token
    Agent->>Worker: POST /mcp (Authorization: Bearer <token>)
    Worker->>Web: Proxy agent API call with user token

OAuth Endpoints

Endpoint	Method	Purpose
`/.well-known/oauth-protected-resource`	`GET`	RFC 9728 Protected Resource Metadata declaring resource identifiers and supported scopes.
`/.well-known/oauth-authorization-server`	`GET`	RFC 8414 OAuth Server Metadata advertising endpoints, PKCE methods, and client authentication modes.
`/oauth/authorize`	`GET`	Initiates the authorization code flow, redirecting to the user consent view.
`/oauth/token`	`POST`	Exchanges authorization codes for tokens or refreshes an expired access token.
`/oauth/revoke`	`POST`	Revokes an active access or refresh token.
`/oauth/register`	`POST`	RFC 7591 Dynamic Client Registration endpoint for compatible clients.

Client ID Metadata Documents (CIMD)

For clients like ChatGPT, Kalpana supports Client ID Metadata Documents (CIMD). Instead of requiring developers to manually generate and copy client credentials into ChatGPT:

ChatGPT provides its verified URL client identifier: https://chatgpt.com/oauth/.../client.json
Kalpana fetches and verifies the document against documented callback domains.
The client registers seamlessly without insecure manual client secret distribution.

Dynamic Client Registration (RFC 7591) remains available as a fallback for agents and local tools that do not support CIMD.

PKCE Requirement

All authorization requests must include PKCE with code_challenge_method=S256:

code_challenge: Base64URL-encoded SHA-256 hash of a 43–128 character high-entropy random verifier string.
code_challenge_method: Must strictly be S256. Plain PKCE is rejected.

Permission Scopes

During consent, the user grants permissions that bound what the agent can inspect or modify:

Scope	Allowed Operations
`templates:read`	Search templates and inspect exposed input variables (`search_templates`, `get_template_inputs`).
`assets:read`	Search and preview ready image assets in authorized workspaces (`search_assets`).
`assets:create`	Upload new assets into an authorized workspace.
`batches:read`	Inspect batch details, query execution progress, and list recent batches (`get_batch`, `list_batches`).
`batches:create`	Validate row data, stage pending batches, and start rendering (`validate_batch`, `create_batch`, `run_batch`).
`renders:read`	Check individual render status and logs.
`creatives:read`	Retrieve download links for finished creative outputs (`get_batch_outputs`).

Token Security & Lifecycle

Opaque Tokens: Access and refresh tokens are cryptographically random, high-entropy opaque strings.
SHA-256 Hashed Storage: The backend stores only SHA-256 hashes of tokens, preventing token extraction from database snapshots.
Short-Lived Access: Access tokens expire quickly and are renewed using rotating refresh tokens.
Automatic Invalidation: Refreshing a token immediately invalidates the previous refresh token.
Rate-Limit Key Privacy: The Cloudflare Worker never uses raw bearer tokens as rate-limit keys or logging attributes; it computes an opaque HMAC key to track usage.

Authentication & OAuth 2.0