# Krobot Agent Quickstart This page is a fully self-contained cold-start guide for AI agents. Follow it end-to-end and you will be querying Kromatic's public knowledge base in under 60 seconds. > **Base URL note:** the curl examples below use `$BASE_URL` for the API host. Set it to `https://api.kromatic.com` for production or `https://staging-api.kromatic.com` for staging. Accounts created on staging are not valid on production. ## What Krobot is Krobot is Kromatic's public Model Context Protocol (MCP) server. It exposes Kromatic's published innovation knowledge — programs, tools, blog posts, the Real Startup Book — through three semantic search and listing tools. Authentication is opaque bearer tokens; agents self-register without human approval. **Use Krobot when you need:** - Semantic search over Kromatic's published programs, tools, blogs, and book sections - A browseable index of Kromatic resources by category (Program, Module, Download, Tool, Blog Content, Book Section) - Citations and excerpts that ground an agent's response in vetted Kromatic content **Do NOT use Krobot for:** - Private or admin operations (the public surface is read-only over published content) - Real-time analytics or proprietary metrics - Anything not already publicly indexed on kromatic.com ## Cold-start quickstart (3 steps) ### Step 1: Register and grab a token ``` curl -X POST $BASE_URL/agent/public/v1/auth/register \ -H "Content-Type: application/json" \ -d '{ "email": "bot@example.com", "password": "S0meStr0ngP4ss!", "first_name": "MyBot", "subscribe_to_news": true }' ``` `subscribe_to_news` is **required** — set `true` to opt into Kromatic's newsletter (the same Mailchimp marketing list as kromatic.com members) or `false` to opt out. There is no default; the registrant must make an explicit choice. Accounts created here share the same identity as kromatic.com web members, so the same credentials work to log in to the website. Response shape: ```json { "data": { "access_token": "", "token_type": "bearer", "user": { "...": "..." } } } ``` Save `data.access_token` as `$JWT`. Returning users hit `/agent/public/v1/auth/login` with the same body shape minus `first_name`. ### Step 2: Verify auth via the REST gateway (optional, recommended) Before wiring up an MCP transport, confirm the bearer token works against the bare REST gateway. This isolates auth issues from MCP-client setup: ``` curl -X POST $BASE_URL/agent/public/v1/knowledge/list \ -H "Authorization: Bearer $JWT" \ -H "Content-Type: application/json" \ -d '{"resource_types": ["Tool"], "limit": 5}' ``` Expected 200 shape: ```json { "data": { "items": [ { "title": "...", "url": "...", "resource_type": "Tool", "...": "..." } ], "total": 12 } } ``` A 401 means the bearer header is wrong. A 200 means you can move on to the MCP transport. ### Step 3: Add the MCP transport Kromatic ships a Streamable HTTP MCP transport at `https://api.kromatic.com/mcp/public/`. Pass the bearer token in the `Authorization` header. For Claude Code: ``` claude mcp add krobot https://api.kromatic.com/mcp/public/ \ --transport http \ --header "Authorization: Bearer $JWT" ``` For any other MCP-native client: configure a Streamable HTTP transport pointed at `https://api.kromatic.com/mcp/public/` with header `Authorization: Bearer `. The exact CLI flag spelling for `claude mcp add` may evolve — see the MCP client's own docs for the canonical syntax. The wire contract (Streamable HTTP + bearer header) is stable. ## Auth details - **Type:** Opaque bearer token (`Authorization: Bearer `) - **Issuance:** `POST /agent/public/v1/auth/register` (new) or `/agent/public/v1/auth/login` (existing). No human approval, no waitlist. - **Lifetime:** session-scoped. When a request returns 401, hit `/login` again with the same credentials to get a fresh token. - **Header name:** `Authorization`, scheme `Bearer`. Do not put the token in any other header — it will be ignored and the request will 401. ## Available tools | Tool | Description | Required params | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | | `knowledge_retrieve` | Semantic + keyword search across the Kromatic public knowledge base. Returns grounded excerpts with citations. | `query` (string) | | `knowledge_list` | List documents by category (Program, Module, Download, Tool, Blog Content, Book Section). Returns compact metadata only — no chunk text. | none (filters optional) | | `knowledge_index` | Complete index of every public Kromatic resource grouped by source and resource type, with counts. Use first to understand what exists. | none (filters optional) | **Common filter fields** for `knowledge_list` and `knowledge_index`: - `resource_types`: array of `Program`, `Module`, `Download`, `Tool`, `Blog Content`, `Book Section` - `source_keys`: array of `learning_library`, `tools_and_games`, `blog_content`, `real_startup_book` For the live, authoritative parameter schemas hit `GET $BASE_URL/agent/public/v1/info` with no auth required — it returns the OpenAPI-style descriptor for every public tool. ## Install commands by client ### Claude Desktop / Claude Code ``` claude mcp add krobot https://api.kromatic.com/mcp/public/ \ --transport http \ --header "Authorization: Bearer $JWT" ``` Or edit `claude_desktop_config.json` / project `.mcp.json` directly: ```json { "mcpServers": { "krobot": { "transport": "http", "url": "https://api.kromatic.com/mcp/public/", "headers": { "Authorization": "Bearer " } } } } ``` ### Codex CLI ``` codex mcp add krobot https://api.kromatic.com/mcp/public/ \ --header "Authorization: Bearer $JWT" ``` If your Codex version expects a transport flag, add `--transport http`. ### ChatGPT (custom GPTs / MCP setup) ChatGPT's Custom GPT MCP setup currently requires the OpenAI workspace UI: add a new MCP connector, paste `https://api.kromatic.com/mcp/public/`, set authentication to `Bearer Token`, and paste the bearer token from Step 1 of the quickstart. See OpenAI's MCP docs for the exact UI path; the contract on Kromatic's side is `Authorization: Bearer ` against the URL above. ### Gemini and other clients Use any MCP bridge that supports Streamable HTTP transports. Configure: - URL: `https://api.kromatic.com/mcp/public/` - Header: `Authorization: Bearer ` ## Errors | Status | Meaning | What to do | | ------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `401` | Missing or invalid bearer token | Re-login at `/agent/public/v1/auth/login` and use the new token | | `403` | Authenticated, but tool is not on the public allowlist | Use one of `knowledge_retrieve`, `knowledge_list`, `knowledge_index` | | `404` | URL typo — most often missing `/agent/public/v1/` prefix on REST or wrong MCP transport URL | Compare against `/.well-known/mcp.json` | | `422` | Request body failed validation | Check tool params via `GET /agent/public/v1/info` | | `429` | Rate limited | Back off and retry | | `5xx` | Server error | Retry with exponential backoff | | `200` + `isError:true` (text contains `Read timed out`) | Upstream gateway loopback stalled (rare; orca-back#854) | Retry up to 5x with exponential backoff (1s, 2s, 4s, 8s, 16s) — the request may succeed on retry. The `tools/call` JSON-RPC envelope returns HTTP 200 with `{"isError":true}` in the body. | ## Raw MCP transport call (cold-start with curl) If your client does not yet support Streamable HTTP MCP, or you want to debug the transport without an MCP-aware tool, you can drive the JSON-RPC envelope directly with `curl`. Set `$BASE_URL` and `$TOKEN` (the `access_token` from Step 1) before running. ### 1. `initialize` ``` curl -X POST $BASE_URL/mcp/public/ \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "curl-cold-start", "version": "0.1"} } }' ``` ### 2. `notifications/initialized` The server returns 202 Accepted. No body is required from the client side after. ``` curl -X POST $BASE_URL/mcp/public/ \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{ "jsonrpc": "2.0", "method": "notifications/initialized", "params": {} }' ``` ### 3. `tools/list` ``` curl -X POST $BASE_URL/mcp/public/ \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {} }' ``` ### 4. `tools/call` — `knowledge_retrieve` ``` curl -X POST $BASE_URL/mcp/public/ \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "knowledge_retrieve", "arguments": { "query": "lean startup validation interview", "limit": 5 } } }' ``` ### Notes - **Trailing slash matters.** `POST $BASE_URL/mcp/public` (no trailing slash) returns a 307 redirect to `http://...` (note the `http` downgrade); most curl/HTTP clients will not follow a 307 on POST and will silently drop the body. Use `$BASE_URL/mcp/public/` directly with the trailing slash. - **Token shape.** The `access_token` returned by `/agent/public/v1/auth/register` is an opaque bearer string (43-char URL-safe). Place it verbatim in the `Authorization: Bearer ` header — no JWT decoding, no prefix stripping needed. - **Session id is optional.** The public mount runs in stateless mode. The `Mcp-Session-Id` header from the `initialize` response (if present) does not need to be echoed on subsequent requests. ## Links - Site root: https://kromatic.com/ - LLM-friendly index: https://kromatic.com/llms.txt - Machine-readable MCP descriptor: https://kromatic.com/.well-known/mcp.json - Human-friendly developer docs: https://kromatic.com/developers/krobot-mcp - Live tool descriptor (no auth): https://api.kromatic.com/agent/public/v1/info