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_64

Auth, 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.

Install

Get the CLI or configure your MCP client.

Initialize

Point the client at https://raccha.ai/mcp.

Authenticate

Run raccha auth login or approve a device code.

Logout

raccha auth logout clears local credentials.

Claude Code

CLI

Add 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

Config

Paste this into claude_desktop_config.json. OAuth redirect requires a browser paste.

{
  "mcpServers": {
    "raccha": {
      "url": "https://raccha.ai/mcp"
    }
  }
}

Cursor

Config

Add to project .cursor/mcp.json or global ~/.cursor/mcp.json.

{
  "mcpServers": {
    "raccha": {
      "url": "https://raccha.ai/mcp"
    }
  }
}

Windsurf

Bridge

Uses 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 public

Expected 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 public

Config-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

API

Remote 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"
)
Approval is always required. After you add the server, your agent will print a short code like 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.
Listed on partner directories. Find raccha.ai in the mcp.so server directory and other MCP registries.

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

Wheel

OpenAPI-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

Tarball

openapi-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

Jar

OpenAPI-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.
Verify what you download. The installer is served over HTTPS and can be inspected before execution. For SDK artifacts, compare the SHA-256 checksum listed on the downloads page after pulling a release. The OpenAPI spec and generated clients are version-locked, so they cannot drift.

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
Need the raw API? The generated OpenAPI spec and Swagger UI describe every route. SDKs regenerate from that same spec, so they cannot drift.