Connect
One command, then your agent or language.
Start with the universal installer, then wire raccha.ai into your agent or IDE, or pull a generated language SDK.
Universal installer
Linux x86_64Auth, KV, queue, stats, and stateless tools — one binary, one-shot commands or an interactive REPL.
curl -fsSL https://raccha.ai/install.sh | bash -s -- -y
Inspect first with curl -fsSL https://raccha.ai/install.sh -o install.sh && less install.sh, or preview with --dry-run.
After install, approve the device at raccha.ai/device.
Connect from your agent or IDE
raccha.ai is a remote MCP server at https://raccha.ai/mcp.
Pick your agent, paste the config or run the command, then approve the device-code request at /device.html.
Get the CLI or configure your MCP client.
Point the client at https://raccha.ai/mcp.
Run raccha auth login or approve a device code.
raccha auth logout clears local credentials.
Claude Code
CLIAdd the server, then authenticate with OAuth 2.1 + PKCE. Run once per organization for multi-org accounts.
# Add the server claude mcp add --transport http raccha https://raccha.ai/mcp # Authenticate (interactive terminal only) claude mcp login raccha # Switch organization if you belong to more than one claude mcp login raccha --switch-org
Claude Desktop
ConfigPaste this into claude_desktop_config.json. OAuth redirect requires a browser paste.
{
"mcpServers": {
"raccha": {
"url": "https://raccha.ai/mcp"
}
}
}
Cursor
ConfigAdd to project .cursor/mcp.json or global ~/.cursor/mcp.json.
{
"mcpServers": {
"raccha": {
"url": "https://raccha.ai/mcp"
}
}
}
Windsurf
BridgeUses npx -y mcp-remote. Requires Node.js 20+; Ubuntu stock Node 18 will crash.
{
"mcpServers": {
"raccha": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://raccha.ai/mcp"
]
}
}
}
Kimi Code
Not publicExpected command shape once a public Kimi CLI is available.
# Not installable from npm yet # Expected command when available: # kimi mcp add --transport http raccha https://raccha.ai/mcp
OpenCode
Not publicConfig-file shape for the OpenCode agent. Cannot be exercised until a public client ships.
{
"mcp": {
"raccha": {
"type": "remote",
"url": "https://raccha.ai/mcp",
"enabled": true
}
}
}
OpenAI
APIRemote MCP with openai>=1.40. Requires OpenAI API key and account access to remote MCP.
from openai import OpenAI client = OpenAI() response = client.responses.create( model="gpt-4o-mini", tools=[{ "type": "mcp", "server_label": "raccha", "server_url": "https://raccha.ai/mcp", "authorization": "rk_... or access_key", "require_approval": "auto" }], input="List my KV namespaces" )
ABCD-1234. Open raccha.ai/device.html,
sign in, enter that code, and approve the device. Until you approve, no tool call runs.
Multi-org accounts. raccha.ai issues one OAuth token per organization. If the same email belongs to multiple orgs, run
claude mcp login raccha once per org or call the list_profiles / switch_org MCP tools to save additional org credentials locally. Each credential is scoped to exactly one org; there is no single token that spans all orgs.
Authentication from a server is headless.
raccha auth login is magic-link only (needs an inbox). For servers, containers, and CI, use
raccha auth device-login, then approve the code in a browser that is already signed in.
Language SDKs
Download the same generated clients we use ourselves. The OpenAPI spec now declares Bearer auth, so regenerated clients auto-send your credential; the current wheel needs the manual header shown below.
Python
WheelOpenAPI-generated, typed models, urllib3-based.
# Use a virtual environment (PEP 668) curl -LO https://raccha.ai/downloads/raccha_client-0.1.0-py3-none-any.whl python3 -m venv .venv source .venv/bin/activate pip install raccha_client-0.1.0-py3-none-any.whl # Authenticated KV call python3 - <<'PY' from raccha_client.api.kv_api import KvApi from raccha_client.api_client import ApiClient from raccha_client.configuration import Configuration from raccha_client.models.put_body import PutBody cfg = Configuration(host='https://raccha.ai') client = ApiClient(cfg) client.default_headers['Authorization'] = 'Bearer rk_...' api = KvApi(client) api.put_kv_slug_key('my-key', '<slug>', PutBody(value='hello')) print(api.get_kv_slug_key('my-key', '<slug>')) PY # Stateless tool python3 - <<'PY' from raccha_client.api.tools_api import ToolsApi from raccha_client.api_client import ApiClient from raccha_client.configuration import Configuration from raccha_client.models.hash_body import HashBody api = ToolsApi(ApiClient(Configuration(host='https://raccha.ai'))) print(api.post_tools_hash(HashBody(input='hello'))) PY
TypeScript
Tarballopenapi-typescript types with a thin openapi-fetch wrapper. ESM only.
curl -LO https://raccha.ai/downloads/raccha-0.1.0.tgz npm install ./raccha-0.1.0.tgz // package.json: add "type": "module" or use a .mjs file import { createRacchaClient } from 'raccha'; const client = createRacchaClient({ baseUrl: 'https://raccha.ai', ownerKey: 'rk_...' }); await client.PUT('/kv/{slug}/{key}', { params: { path: { slug: '<slug>', key: 'my-key' } }, body: { value: 'hello' } }); const { data } = await client.GET('/kv/{slug}/{key}', { params: { path: { slug: '<slug>', key: 'my-key' } } }); console.log(data);
Java
JarOpenAPI-generated, Java 8+ dates, Jakarta EE. Install the jar into your local Maven repo.
curl -LO https://raccha.ai/downloads/raccha-client-0.1.0.jar mvn install:install-file -Dfile=raccha-client-0.1.0.jar \ -DgroupId=ai.raccha -DartifactId=raccha-client -Dversion=0.1.0 -Dpackaging=jar
OS support
| Platform | CLI binary | Python SDK | TypeScript SDK | Notes |
|---|---|---|---|---|
| Linux x86_64 | Supported | Supported | Supported | Primary target. glibc-based distributions. |
| macOS Apple Silicon / Intel | Supported | Supported | Supported | Universal binary where available. |
| Windows (WSL2) | Supported | Supported | Supported | Run inside WSL2; native Windows is not tested. |
| Linux ARM64 | Not yet | Supported | Supported | SDKs work; CLI binary is on the roadmap. |
Quick starts
Verify the MCP server
Capture the session id; follow-up calls need the mcp-session-id header.
SESSION=$(curl -fsSL -X POST https://raccha.ai/mcp \
-H 'Accept: application/json, text/event-stream' \
-H 'Content-Type: application/json' \
-D /tmp/mcp-headers.txt \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}' >/dev/null 2>&1 \
&& grep -i mcp-session-id /tmp/mcp-headers.txt | awk '{print $2}' | tr -d '\r')
curl -sSL -X POST https://raccha.ai/mcp \
-H 'Accept: application/json, text/event-stream' \
-H 'Content-Type: application/json' \
-H "mcp-session-id: $SESSION" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
CLI: try a stateless tool
No auth needed. The CLI uses positional arguments.
raccha tools hash hello raccha tools jwt-decode 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
CLI: sign in from a server
Start device-code login, then approve the code at /device.html.
raccha auth device-login