DOCUMENTATION

Connect your AI app

Keep working in Codex, Claude Code, or a compatible MCP client while using Cookbook’s recipes and approved brand context. Your app does the generation; Cookbook keeps foundations and saved work available for review.

Set up a connection

Open Settings and choose Connect your AI app.
Choose your client, name the connection, and select its permissions. Each key is bound to one Cookbook project you own.
Copy the key when it is shown. Follow the client instructions and connector installation guidance below for a local source build.
Enter the key through the connector’s hidden local prompt. Restart your AI app if needed, then ask it to list Cookbook recipes and read your approved context.

Connector source lives in packages/cookbook-mcp. Use the installation instructions for the version you run. The connector checks connectivity and registers a local stdio bridge; its private configuration file stores your key. Never paste the key into an AI conversation or include it in command arguments.

Codex and Claude Code are the initial supported clients. Other compatible clients use manual configuration. Browser-only clients requiring OAuth are not included in this launch. Replace a key by creating a new connection, reconnecting your app, and revoking the old key in Settings.

Build the local connector

With Node.js 22 or newer and pnpm installed, open a local checkout of the repository. Run pnpm install --frozen-lockfile, then pnpm build:mcp from its root. The build creates packages/cookbook-mcp/dist/cli.mjs.

For Codex, run node packages/cookbook-mcp/dist/cli.mjs connect --client codex. For Claude Code, replace codex with claude-code. The selected client’s CLI must be installed and available in your terminal.

Use --client manual to print configuration for another compatible client. Add --url followed by your installation’s HTTPS URL for self-hosting. If a registration already uses the name, choose another with --name; the connector does not silently replace it. Keep the built connector and its private configuration file in place after registration.

Choose permissions

context:read reads approved foundations and saved deliverables.
foundations:write proposes foundation updates for human review; available on free hosted accounts.
artifacts:write saves other deliverables as drafts; requires paid hosting.

Permissions do not override hosted plan limits. No permission accepts foundation changes. Using your own AI app consumes that app’s subscription or provider credentials.

MCP interface

MCP—the Model Context Protocol—lets your app discover Cookbook tools. Remote MCP uses Streamable HTTP at /mcp. The local stdio bridge calls the same REST API and can target a hosted or self-hosted Cookbook URL.

list_recipes and get_recipe retrieve deployed recipes and mode guidance.
get_brand_context reads approved foundations.
update_brand_context returns a proposal marked pending review, with a Cookbook review link.
save_deliverable, list_deliverables, and get_deliverable save or retrieve permitted work.

Resources are available at cookbook://pantry/brand-context and cookbook://recipes/{slug}. The customer-interview-synthesizer prompt accepts interview notes and an optional research goal. Rendering the prompt includes approved context; it does not itself call a model.

REST API

Recipe reads are public. Other endpoints require a connection key in the Authorization: Bearer header. Browser cookies and Supabase administrator credentials are not integration credentials.

GET /api/v1/skills: Public recipe metadata, versions, and foundational status.
GET /api/v1/skills/:slug: Complete recipe Markdown; optional mode: setup, apply, tune, or validate.
GET /api/v1/pantry: Approved foundation content, latest versions, and pending-update indicators.
PATCH /api/v1/pantry: Create a foundation proposal and return its review URL.
POST /api/v1/artifacts: Save an externally generated deliverable as a draft; paid hosting required.
GET /api/v1/artifacts: List saved deliverables with limit and cursor pagination.
GET /api/v1/artifacts/:id: Read an owned deliverable and its content.
GET /api/v1/connection: Check connection identity, permissions, and hosted entitlements.

Write requests and versions

Foundation keys are brand, audience, voice, content, proof, and guardrails. Pantry reads separate approvedContent and approvedVersion from latestVersion and pending. Use approved content for generation and the latest version when proposing an edit.

A foundation request contains a UUID requestId and an updates array. Each update supplies key, Markdown content, sources, and expectedVersion. Each section allows 20,000 characters and exactly one Markdown title. The response includes a proposal ID and review URL; the change is still pending.

A deliverable request supplies a UUID requestId, a published skillSlug, title, and contentMarkdown up to 60,000 characters. Optional metadata is bounded; optional agentName identifies the generating app on either write. A successful save returns the saved ID and Cookbook URL.

Retry the same write with the same request ID and content. Reusing an ID with different content returns IDEMPOTENCY_CONFLICT. On STALE_VERSION, read the latest document and review the change before submitting a new request. Never treat a pending draft as an approved fact.

Troubleshooting

AUTH_REQUIRED means the key is missing, invalid, expired, or revoked. FORBIDDEN indicates missing permission; PLAN_REQUIRED indicates a hosted entitlement requirement. Fix invalid fields on INVALID_REQUEST, and respect the retry delay on RATE_LIMITED. List requests accept limit from 1 to 100 and an opaque cursor; use the returned nextCursor for the next page.