Questions, answered plainly.

What is raccha.ai?

A small, sharp toolbox for agents: namespace-scoped key-value storage, FIFO queues, identity and scoped access, and stateless utility tools. Everything is reachable natively over MCP or plain HTTP, authenticated by a bearer credential bound to an account rather than a password.

How does an agent or script authenticate?

Every route except /auth/request-link and /auth/verify requires a credential, sent as Authorization: Bearer <key> or (browser-only) an HttpOnly session cookie set by /auth/verify. A request with neither returns 401 "missing credential"; a malformed, unknown, or revoked credential returns 401 "invalid credential" — deliberately indistinguishable.

Two credential shapes:

• owner_key — unrestricted access to one account, minted on sign-in.
• access_key — scoped down to specific role_ids. Use this for anything handed to a third party or lower-trust automation; never share an owner_key.

How does a credential actually get minted?

• Magic link — for humans with a browser. POST /auth/request-link with an email, click the link, and verify. One owner_key is returned per organization that email belongs to.
• Device-code flow — for CLIs, MCP clients, or anything without its own browser. POST /auth/device/code receives a device_code and human-readable user_code. The human approves the code at /device.html from a signed-in browser, while the client polls /auth/device/token.
• Invite — an existing admin invites a new member, who follows the same magic-link mechanics.

What can I actually call?

• GET/PUT /kv/{slug}/{key} — namespace-scoped KV storage.
• POST /queue/{slug}/push/{name} and POST /queue/{slug}/pop/{name} — FIFO queue per namespace.
• GET /stats — per-account usage counts.
• /admin/roles and /admin/access-keys — scoped credential lifecycle.
• POST /tools/jwt-decode, /tools/hash, /tools/cert-inspect, /tools/ip-cidr — stateless utilities, no account required.

Full schemas and try-it-out UI are at /docs/.

Is there a real MCP transport, or just an HTTP API?

A real MCP server is live at this origin, mounted at /mcp. Every route above is also exposed as a generated MCP tool, built directly from the same OpenAPI contract the HTTP routes are generated from, so the two surfaces cannot drift.

What is stateful, stateless, and still building?

• Stateful today: KV, queue, account/role/access-key records, usage stats.
• Stateless today: the four /tools/* utilities.
• Building: webhook relay, namespace mailbox addresses, and published package-registry listings for the SDKs. The SDKs themselves are downloadable directly from this site today.

What happens if I get rate-limited?

Auth endpoints are per-IP rate-limited. Expect 429 on abuse rather than a silent hang; back off and retry rather than hammering on failure.