Kalpana MCP Documentation

Step-by-step guides for connecting ChatGPT, Claude Desktop, Cursor, and custom MCP clients.

Connect your preferred client or IDE to the Kalpana MCP gateway.

Supported Clients

Client	Protocol Support	Auth Flow	Setup Complexity
ChatGPT	Streamable HTTP	CIMD Automatic OAuth	Low (1-click)
Claude Desktop	Streamable HTTP / SSE	OAuth / Bearer Token	Low (Config file)
Cursor IDE	Streamable HTTP / SSE	OAuth / Bearer Token	Low (Settings UI)
Codex	Agent Plugins Bundle	Plugin Package	Low (CLI)
Custom Agents	Streamable HTTP JSON-RPC	OAuth Bearer Header	Standard SDK

Detailed Setup Instructions

Connecting in ChatGPT Developer Mode

ChatGPT connects to Kalpana using Client ID Metadata Documents (CIMD):

Open ChatGPT Settings

Go to Settings → Security and login → Developer mode and turn it On.

Add MCP Server

Visit https://chatgpt.com/plugins, click Add (+), and provide the endpoint:

https://mcp.kalpana.one/mcp

ChatGPT will load the OAuth metadata and redirect you to Kalpana's consent page. Log in and confirm the requested permissions.

Configuring Claude Desktop

Edit your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "kalpana": {
      "url": "https://mcp.kalpana.one/mcp"
    }
  }
}

Restart Claude Desktop to load the tools.

Configuring Cursor IDE

Open Cursor and navigate to Settings → Features → MCP Servers.
Click + Add New MCP Server.
Fill in the connection form:
- Name: kalpana
- Type: http (or sse)
- URL: https://mcp.kalpana.one/mcp
Save the configuration and verify the status shows a green dot.

Using the Codex Agent Plugin

The Kalpana repository provides a pre-packaged Agent Plugin in apps/mcp-server/plugin/kalpana.

To validate and link the plugin into your Codex environment:

python3 "$CODEX_HOME/skills/.system/plugin-creator/scripts/validate_plugin.py" \
  apps/mcp-server/plugin/kalpana

This package automatically bundles:

plugin.json: Portable metadata.
mcp.json: Endpoint definition pointing to https://mcp.kalpana.one/mcp.
skills/create-creative-batch: Built-in safe batch creation skill.

Integrating with the TypeScript SDK

You can connect to Kalpana MCP directly from Node.js, Bun, or Deno using @modelcontextprotocol/sdk:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://mcp.kalpana.one/mcp"),
  {
    headers: {
      Authorization: `Bearer ${process.env.KALPANA_OAUTH_TOKEN}`,
    },
  }
);

const client = new Client(
  { name: "my-custom-agent", version: "1.0.0" },
  { capabilities: {} }
);

await client.connect(transport);

// List available tools
const tools = await client.listTools();
console.log("Tools:", tools);

// Call a tool
const workspaces = await client.callTool({
  name: "list_workspaces",
  arguments: {},
});
console.log("Workspaces:", workspaces);

Client Setup Guides