CKF as an MCP Server

Single Streamable HTTP endpoint, JSON-RPC 2.0 over POST. No SDK to install.

https://compiledknowledgeformat.org/api/mcp

Public by default. The default ckf.compile tool runs the heuristic compiler in-process — it never calls an upstream LLM, so it cannot fail on quota or provider outage. For the LLM upgrade (ckf.compile_llm), pass byok_key with any supported provider, or send Authorization: Bearer <supabase-jwt> to unlock Advanced AI (admin / allowlist only).

Every MCP client gets a working compile path out of the box via ckf.compile. The heuristic compiler is in-process, instant and structurally consistent — perfect when you need a guaranteed CKF package with no setup. When you want richer inference (better paraphrase, denser concepts/rules/QA) and to reduce composition hallucination, switch the same call to ckf.compile_llm with your own provider key (BYOK) — or use Advanced AI if you are on the allowlist. Side-by-side comparison: /compiler-heuristic-vs-llm.

List the available tools:

curl -X POST https://compiledknowledgeformat.org/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Compile some text into CKF (default — heuristic, instant, no key, always works):

curl -X POST https://compiledknowledgeformat.org/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0","id":2,"method":"tools/call",
    "params":{
      "name":"ckf.compile",
      "arguments":{
        "text":"Spaced repetition strengthens memory by reactivating knowledge over increasing intervals. Sleep supports consolidation.",
        "format":"markdown"
      }
    }
  }'

Works without any key. For higher-fidelity extraction, swap to ckf.compile_llm with byok_key (see the BYOK section below).

Add the CKF server to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\\Claude\\claude_desktop_config.json (Windows). Restart Claude.

{
  "mcpServers": {
    "ckf": {
      "url": "https://compiledknowledgeformat.org/api/mcp"
    }
  }
}

After restart, Claude lists CKF tools under the 🔌 icon. Try: "Use ckf.search_posts to find articles about agentic AI, then fetch the top one and summarize the rules."

Both IDEs read MCP servers from ~/.cursor/mcp.json or the equivalent Windsurf settings file:

{
  "mcpServers": {
    "ckf": { "url": "https://compiledknowledgeformat.org/api/mcp" }
  }
}

From any chat, ask the agent: "Compile the selected text into CKF and save it next to this file."

All read-only tools and the default heuristic ckf.compile are free, no-auth and rate-limited per IP — they always work out of the box. ckf.compile_llm is the opt-in quality upgrade and requires either a BYOK key (any provider) or an admin/allowlist Supabase JWT for the provider="lovable" Advanced AI path.

• ckf.compile — default. Instant heuristic compile, text → CkfPackage. Free, no auth, zero-config; never fails on quota or upstream outage.
• ckf.compile_llm — opt-in quality upgrade. Single-chunk LLM compile through the full v1.3.1 pipeline. Pass byok_key for any provider (OpenAI, Anthropic, Google, DeepSeek, OpenRouter), or use provider="lovable" only with an admin/allowlist JWT. Accepts an optional coverage_mode (summary | balanced | complete); the response carries metrics.preflight, metrics.coverage and metrics.numeric_integrity alongside the existing sanitizer/promotion/quality fields. Produces richer inference and materially reduces composition hallucination versus the heuristic (see comparison). Hard cap: 60k input characters; per-user and global daily quotas apply to the Lovable path; the kill-switch MCP_LOVABLE_AI_DISABLED forces BYOK for everyone when set. Canonical metadata extraction (v1.3.1): for PDF inputs the pipeline scans the front-matter (pages 1–5) and back-matter (last 3 pages) with deterministic heuristics and overrides any LLM-inferred bibliographic fields. The returned package includes source_title, source_subtitle, source_authors[], source_author, source_edition, source_publisher, source_year and source_isbn when found; source_type uses a controlled vocabulary ("PDF e-book" or "PDF document"). Every override is recorded as an auditable warning in metrics.warnings.
• ckf.parse — parse any CKF document (json/yaml/markdown) into a normalized object.
• ckf.serialize — render a CkfPackage as json, yaml, or markdown.
• ckf.validate — schema-check a CKF document, return errors[] for self-correction.
• ckf.example — return a curated CKF package. topic ∈ learning | business | clinical | legal | engineering | scientific.
• ckf.search_posts — search published CKF news posts by keyword.
• ckf.fetch_post — fetch one news post as a CKF package by slug.
• ckf.viewer_url — build a human-friendly /viewer URL from a package or .ckf URL.
• ckf.diff — structural diff of two CKF packages.

The server also exposes MCP resources for direct reads by URI:

• ckf://post/<slug> — any published news post as a CKF package.
• ckf://example/learning, ckf://example/business, ckf://example/clinical, ckf://example/legal, ckf://example/engineering, ckf://example/scientific — curated samples.
• ckf://schema/v0.2 — the JSON schema used by the compiler.

The CKF MCP server is open source — implementation, tools, and prompts live in the CKF repo on GitHub. You can self-host it, audit it, or extend it.

AI credits for ckf.compile_llm are your responsibility. The hosted endpoint at compiledknowledgeformat.org/api/mcp only spends Lovable AI credits for project admins and users on the compiler allowlist; everyone else must pass byok_key with their own provider key. This keeps the public endpoint free to operate while giving you full control over which model and budget you use.

• Get a Gemini key at aistudio.google.com/app/apikey (free tier available).
• Get an OpenAI key at platform.openai.com/api-keys.
• See BYOK providers for the full list and pricing notes.

Pass the key as byok_key in the tool arguments (see the BYOK example below). Keys are never stored, never logged, never written to the database — they are used once to call the upstream provider and discarded.

Two prompt templates ship out of the box and appear in the client's prompt picker:

• talk-to-article (slug) — loads a post via ckf.fetch_post and answers strictly from the package, citing source_refs.
• compile-and-critique (text) — compiles then returns a structured critique of missing concepts, weak rules, and improvement suggestions.

Pass byok_key in the tool arguments. Keys are never stored or logged. Five providers are supported — see BYOK providers.

{
  "jsonrpc":"2.0","id":3,"method":"tools/call",
  "params":{
    "name":"ckf.compile_llm",
    "arguments":{
      "text":"...your source text up to 60k chars...",
      "provider":"openai",
      "model":"gpt-5-mini",
      "byok_key":"sk-...",
      "language":"en",
      "format":"json"
    }
  }
}

The language argument enforces the hard language lock — every prose field in the resulting package will match it (see Language lock). The response also carries a metrics object with compiler_version and sanitizer counters. For larger sources use the full chunked pipeline at /compiler.

Errors are surfaced in two places: JSON-RPC envelope errors (error.code is a numeric JSON-RPC code, error.data.code is a stable string) for protocol-level failures, and tool-execution errors (result.isError: true with structuredContent.error) for failures inside a tool. Both shapes expose the same fields so clients can retry or self-correct without parsing English.

// JSON-RPC envelope (protocol-level, e.g. unknown method/tool)
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Tool not found: ckf.unknown",
    "data": {
      "code": "TOOL_NOT_FOUND",
      "retryable": false,
      "tool": "ckf.unknown",
      "available": ["ckf.compile", "ckf.compile_llm", "..."]
    }
  }
}

// Tool-execution error (validation, upstream, rate limit)
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "isError": true,
    "content": [{ "type": "text", "text": "[OUT_OF_RANGE] Field \"text\" is too short (min 20 chars, got 5)" }],
    "structuredContent": {
      "error": {
        "code": "OUT_OF_RANGE",
        "message": "Field \"text\" is too short (min 20 chars, got 5)",
        "retryable": false,
        "field": "text",
        "min": 20,
        "max": 200000,
        "length": 5
      }
    }
  }
}

Recommended client logic: retryable === true → exponential backoff and resend; otherwise read data.field / data.hint and fix the request before retrying.

• Research assistant. "Compile this paper into CKF and answer only from the package." Constrained to package scope; answers carry source spans for traceability.
• IDE knowledge layer. Cursor/Windsurf compile any markdown into a CKF sidecar.
• Custom GPT. ChatGPT calls ckf.search_posts + ckf.fetch_post to ground answers in published CKF content.
• CI validator. A GitHub Action calls ckf.validate on every PR touching .ckf files.
• Multi-agent research. One agent compiles, another critiques via compile-and-critique, a third diffs versions with ckf.diff.
• Notion / Obsidian plugin. Compile pages into CKF and store as structured memory.

Protocol: MCP 2025-03-26 (Streamable HTTP, POST only). Server: ckf-mcp-server v0.2.0. Transport: JSON-RPC 2.0. The schema follows CKF v0.2; new tools may appear under the ckf. namespace but existing inputs/outputs are stable.