Kalpana Docs

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 MCP as Kalpana MCP (mcp.kalpana.one)
    participant User as End User

    Agent->>MCP: GET /.well-known/oauth-authorization-server
    MCP-->>Agent: OAuth Metadata (CIMD, PKCE endpoints)
    Agent->>MCP: GET /oauth/authorize (code_challenge)
    MCP->>User: Kalpana sign-in and consent
    User-->>MCP: Chooses a workspace and approves permissions
    MCP-->>Agent: Authorization Code
    Agent->>MCP: POST /oauth/token (code_verifier)
    MCP-->>Agent: Access Token + Rotating Refresh Token
    Agent->>MCP: POST /mcp/batch (Authorization: Bearer <token>)
    MCP-->>Agent: Tool results

OAuth Endpoints

Endpoint	Method	Purpose
`/.well-known/oauth-protected-resource/mcp/batch`	`GET`	RFC 9728 Protected Resource Metadata for the batch server at `/mcp/batch`, declaring the resource identifier and its scopes. The older `/.well-known/oauth-protected-resource` serves the same for `/mcp`.
`/.well-known/oauth-protected-resource/mcp/designer`	`GET`	RFC 9728 Protected Resource Metadata for the designer server at `/mcp/designer`, with its own 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 chooses one workspace and grants permissions that bound what the agent can inspect or modify. The endpoint advertises only the scopes it uses.

Scope	Allowed Operations
`workspaces:read`	See the connected workspace and what the role allows (`get_workspace`).
`templates:read`	Search templates, inspect their input variables, and check rows (`search_templates`, `get_template_inputs`, `validate_batch`); batch creation and edits need it too.
`assets:read`	Search ready image assets and collections in the connected workspace (`search_assets`; on the designer `find_images` and `list_fonts`).
`assets:create`	Add the user's own images to the connected workspace (`upload_images`, on both servers).
`batches:read`	Inspect batch details, query execution progress, list recent batches, and list a batch's jobs (`get_batch`, `list_batches`, `get_batch_jobs`).
`batches:create`	Stage, edit, run and cancel batches and single jobs (`create_batch`, `update_batch`, `update_job`, `run_batch`, `cancel_batch`, `cancel_job`, `create_job`, `run_job`). `run_batch`, `run_job`, `create_job` with `run`, and the cancel tools also need the `renders:create` permission on the user's workspace role, which `get_workspace` reports.
`renders:read`	Read finished renders; `get_batch_outputs` and `get_job` need it with `batches:read` and `creatives:read`.
`creatives:read`	Retrieve download links for finished creative outputs (`get_batch_outputs`, `get_job`).
`templates:create`	Designer only: create templates and pages (`create_design`, `duplicate`, together with `templates:update`).
`templates:update`	Designer only: change and save templates (every tool that changes a design, `undo`, `rename_page`, `delete_pages`, `create_flow`, `update_flow`, `delete_flow`, `set_template_info`). On the designer, reads, checks and previews need `templates:read`.

Each server asks only for the scopes it uses:

Batch (/mcp/batch): workspaces:read, templates:read, assets:read, assets:create, batches:read, batches:create, renders:read and creatives:read.
Designer (/mcp/designer): workspaces:read, templates:read, templates:create, templates:update, assets:read and assets:create.

A grant that includes templates:update is a designer connection; it is listed as Designer MCP under Settings → Connected assistants.

Token Security & Lifecycle

Opaque Tokens: Access and refresh tokens are cryptographically random, high-entropy opaque strings.
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.

Endpoints

https://mcp.kalpana.one exposes the following endpoints:

Endpoint	Method	Description
`/mcp/batch`	`POST`	The batch server: Streamable HTTP MCP endpoint for filling templates and rendering batches. `/mcp` serves it too, for connections made before it moved.
`/mcp/designer`	`POST`	The designer server: Streamable HTTP MCP endpoint for designing and editing templates.
`/.well-known/oauth-protected-resource/mcp/batch`	`GET`	RFC 9728 Protected Resource metadata for `/mcp/batch`, advertising the OAuth server and scopes.
`/.well-known/oauth-protected-resource`	`GET`	The same metadata for the older `/mcp` path.
`/.well-known/oauth-protected-resource/mcp/designer`	`GET`	RFC 9728 Protected Resource metadata for `/mcp/designer`, with the designer's scopes.
`/.well-known/oauth-authorization-server`	`GET`	RFC 8414 Authorization Server metadata supporting CIMD and PKCE.
`/oauth/authorize`	`GET`	Starts authorization code flow; redirects user to Kalpana login & consent screen.
`/oauth/token`	`POST`	Exchanges one-time authorization code or refresh token for access tokens.
`/oauth/revoke`	`POST`	Revokes active OAuth access or refresh tokens.
`/oauth/register`	`POST`	Dynamic client registration endpoint (RFC 7591) for compatible clients.

Some MCP clients target the root origin instead of the documented subpath. The Kalpana server accepts GET requests at / and responds with service metadata pointing to https://mcp.kalpana.one/mcp/batch.