docs(mcp): registry manifest upgrade + multi-client distribution docs

docs/ecosystem.md

@@ -42,6 +42,16 @@ Use **Contentrain Studio** when you need:
 | `@contentrain/rules` | Quality standard and schema/content guardrails | Studio should match the same quality standard in chat, review, and content validation | [Rules & Skills](/packages/rules), [Studio Architecture](https://docs.contentrain.io/developer/architecture) |
 | `@contentrain/skills` | Agent playbooks, workflow hints, and normalize/review procedures | Studio mirrors these workflows in chat-led operations, onboarding, and promotion moments | [Rules & Skills](/packages/rules), [Studio AI Chat](https://docs.contentrain.io/guide/ai-chat) |
 
+## MCP Distribution Surfaces
+
+| Surface | What users see | Best fit |
+|---|---|---|
+| MCP Registry | `io.github.Contentrain/contentrain` | Discover and install the local `@contentrain/mcp` server from MCP-compatible clients |
+| OpenAI Codex | `codex mcp add`, `.codex/config.toml`, and future plugin packaging | Developers who want Contentrain tools inside Codex CLI, desktop, or IDE workflows |
+| Claude Desktop | `claude_desktop_config.json` | Local desktop users who want a checkout-scoped Contentrain server |
+| Claude Code | `claude mcp add`, `.mcp.json`, and plugin marketplaces | Coding-agent workflows with project-scoped MCP approval and skills |
+| Studio MCP Cloud | Hosted Streamable HTTP endpoint + API key | Teams that want external agents to operate a Studio project without sharing a local checkout |
+
 ## Product Philosophy
 
 - **Governance, not generation** — Contentrain standardizes, validates, and reviews content. Your model provider still does the generation.

docs/getting-started.md

@@ -14,7 +14,7 @@ Contentrain AI is an open-source, repo-native content governance stack. Your AI
 
 - Node.js 22+
 - Git
-- An MCP-compatible AI agent (Claude Code, Cursor, Windsurf, or similar)
+- An MCP-compatible AI agent (OpenAI Codex, Claude Desktop, Claude Code, Cursor, Windsurf, or similar)
 
 ## Choose Your Path
 
@@ -78,6 +78,23 @@ npx contentrain setup windsurf      # → creates .windsurf/mcp.json
 npx contentrain setup --all         # → configures all detected IDEs
 ```
 
+OpenAI Codex and Claude Desktop can be connected manually:
+
+```bash
+codex mcp add contentrain -- npx -y contentrain serve --stdio
+```
+
+```json
+{
+  "mcpServers": {
+    "contentrain": {
+      "command": "npx",
+      "args": ["-y", "contentrain", "serve", "--stdio"]
+    }
+  }
+}
+```
+
 ::: tip Auto-configured during init
 If your IDE is detected during `contentrain init`, the MCP config is created automatically — you may already be set up.
 :::
@@ -98,6 +115,8 @@ If your IDE is detected during `contentrain init`, the MCP config is created aut
 
 | IDE | Config file |
 |-----|-------------|
+| OpenAI Codex | `.codex/config.toml` or `~/.codex/config.toml` |
+| Claude Desktop | `claude_desktop_config.json` |
 | Claude Code | `.mcp.json` (project root) |
 | Cursor | `.cursor/mcp.json` |
 | VS Code | `.vscode/mcp.json` |
@@ -115,6 +134,10 @@ npx contentrain serve --mcpHttp --authToken $(openssl rand -hex 32)
 See the [HTTP Transport guide](/guides/http-transport) for auth, deployment patterns, and programmatic embedding.
 :::
 
+::: tip Studio MCP Cloud
+When the project is connected to Studio, Workspace Settings → MCP Cloud creates a hosted Streamable HTTP endpoint and project-scoped API key. Use that endpoint for Codex, Claude Desktop, Claude Code, Cursor, or any MCP client that should operate the Studio project without a local checkout.
+:::
+
 ### 3. Create a content model
 
 Tell your agent:

docs/guides/http-transport.md

@@ -75,6 +75,22 @@ The same pattern works for `createGitLabProvider` with a `GitLabProvider`. Both
 
 ## Deployment patterns
 
+### Studio MCP Cloud
+
+Studio MCP Cloud is the hosted version of the HTTP transport for connected Studio projects. It exposes:
+
+```text
+https://studio.contentrain.io/api/mcp/v1/{projectId}/mcp
+```
+
+Authentication uses a project-scoped MCP Cloud API key:
+
+```http
+Authorization: Bearer <mcp-cloud-key>
+```
+
+Studio handles the gates around that endpoint: project matching, plan access, per-key rate limits, optional tool allowlists, monthly call quotas, usage metering, and branch reconciliation. External clients such as OpenAI Codex, Claude Desktop, Claude Code, Cursor, and custom MCP drivers connect to the same Streamable HTTP shape as a self-hosted `contentrain serve --mcpHttp` server.
+
 ### Studio (hosted agent)
 
 Studio's agent builds a GitHubProvider or GitLabProvider per tenant, points it at the tenant's content repo, and talks to an embedded MCP server over HTTP+LocalProvider-style wiring but with a remote provider. Each session is ephemeral.

docs/packages/mcp.md

@@ -1,6 +1,6 @@
 ---
 title: MCP Tools
-description: Complete reference for @contentrain/mcp — the provider-agnostic MCP engine powering AI content governance with 17 deterministic tools over stdio or HTTP
+description: Complete reference for @contentrain/mcp — the provider-agnostic MCP engine powering AI content governance with 19 deterministic tools over stdio or HTTP
 order: 1
 slug: mcp
 ---
@@ -41,6 +41,18 @@ Optional parser support for higher-quality source scanning:
 - `@astrojs/compiler` — Astro component parsing
 - `svelte` — Svelte component parsing
 
+## Discovery
+
+`@contentrain/mcp` is published for both package-based and registry-based MCP discovery:
+
+- **npm package:** [`@contentrain/mcp`](https://www.npmjs.com/package/@contentrain/mcp)
+- **MCP Registry name:** `io.github.Contentrain/contentrain`
+- **Local server binary:** `contentrain-mcp`
+- **CLI stdio entrypoint:** `contentrain serve --stdio`
+- **Hosted remote endpoint:** Contentrain Studio MCP Cloud at `https://studio.contentrain.io/api/mcp/v1/{projectId}/mcp`
+
+Use the local stdio server when the agent should work against a checkout on your machine. Use Studio MCP Cloud when an external agent should operate a connected Studio project through a project-scoped API key.
+
 ## Tool Catalog
 
 The MCP server exposes **19 tools** organized by function. Each tool includes [MCP annotations](https://spec.modelcontextprotocol.io/specification/2025-03-26/server/tools/#annotations) (`readOnlyHint`, `destructiveHint`, `idempotentHint`) so clients can distinguish safe reads from writes and destructive operations.
@@ -303,6 +315,71 @@ This auto-creates the correct MCP config file and installs AI rules/skills.
 
 Once connected, the agent has access to all 19 MCP tools and can manage your content through natural language.
 
+### OpenAI Codex
+
+Codex uses `~/.codex/config.toml` or a trusted project-scoped `.codex/config.toml`.
+
+```bash
+codex mcp add contentrain -- npx -y contentrain serve --stdio
+```
+
+Equivalent `config.toml`:
+
+```toml
+[mcp_servers.contentrain]
+command = "npx"
+args = ["-y", "contentrain", "serve", "--stdio"]
+```
+
+For Studio MCP Cloud, configure a Streamable HTTP server with the project endpoint and Bearer token:
+
+```toml
+[mcp_servers.contentrain]
+url = "https://studio.contentrain.io/api/mcp/v1/{projectId}/mcp"
+http_headers = { Authorization = "Bearer <mcp-cloud-key>" }
+```
+
+### Claude Desktop
+
+Claude Desktop reads `claude_desktop_config.json`. For a local checkout:
+
+```json
+{
+  "mcpServers": {
+    "contentrain": {
+      "command": "npx",
+      "args": ["-y", "contentrain", "serve", "--stdio"]
+    }
+  }
+}
+```
+
+For Studio MCP Cloud:
+
+```json
+{
+  "mcpServers": {
+    "contentrain": {
+      "type": "http",
+      "url": "https://studio.contentrain.io/api/mcp/v1/{projectId}/mcp",
+      "headers": {
+        "Authorization": "Bearer <mcp-cloud-key>"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+Claude Code can use the project `.mcp.json` generated by `contentrain setup claude-code`, or add the hosted endpoint directly:
+
+```bash
+claude mcp add --transport http contentrain \
+  https://studio.contentrain.io/api/mcp/v1/{projectId}/mcp \
+  --header "Authorization: Bearer <mcp-cloud-key>"
+```
+
 ## Trust Model
 
 | Trust Level | Tools | Risk | Notes |

docs/packages/rules.md

@@ -94,7 +94,7 @@ import {
 } from '@contentrain/rules'
 
 // Check if a tool exists
-console.log(MCP_TOOLS.length)                           // 17
+console.log(MCP_TOOLS.length)                           // 19
 console.log(MCP_TOOLS.includes('contentrain_validate')) // true
 console.log(MCP_TOOLS.includes('contentrain_merge'))    // true
 console.log(MCP_TOOLS.includes('contentrain_doctor'))   // true

packages/mcp/package.json

@@ -3,7 +3,7 @@
   "version": "1.8.1",
   "mcpName": "io.github.Contentrain/contentrain",
   "license": "MIT",
-  "description": "Local-first MCP server for AI-generated content governance — 17 deterministic tools, stdio + HTTP transports, Local / GitHub / GitLab providers",
+  "description": "Local-first MCP server for AI-generated content governance — 19 deterministic tools, stdio + HTTP transports, Local / GitHub / GitLab providers",
   "type": "module",
   "repository": {
     "type": "git",
@@ -26,6 +26,8 @@
     "local-first",
     "platform-independent",
     "claude",
+    "claude-code",
+    "codex",
     "cursor",
     "windsurf"
   ],

packages/mcp/server.json

@@ -1,20 +1,44 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.Contentrain/contentrain",
-  "description": "Local-first MCP server for AI content governance — models, content, validation, i18n",
+  "title": "Contentrain",
+  "description": "Git-native content governance for AI agents — 19 deterministic tools for models, content, validation, normalize, i18n, and review branches.",
+  "websiteUrl": "https://ai.contentrain.io/packages/mcp",
   "repository": {
     "url": "https://github.com/Contentrain/ai",
-    "source": "github"
+    "source": "github",
+    "subfolder": "packages/mcp"
   },
-  "version": "1.0.6",
+  "version": "1.8.1",
   "packages": [
     {
       "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@contentrain/mcp",
-      "version": "1.0.6",
+      "version": "1.8.1",
       "transport": {
         "type": "stdio"
       }
     }
+  ],
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://studio.contentrain.io/api/mcp/v1/{project_id}/mcp",
+      "variables": {
+        "project_id": {
+          "description": "Contentrain Studio project ID for the MCP Cloud endpoint.",
+          "isRequired": true
+        }
+      },
+      "headers": [
+        {
+          "name": "Authorization",
+          "description": "Bearer token using a Contentrain Studio MCP Cloud API key.",
+          "isRequired": true,
+          "isSecret": true
+        }
+      ]
+    }
   ]
 }

packages/rules/README.md

@@ -75,7 +75,7 @@ The package root exports constants for tooling:
 
 - `FIELD_TYPES` — 27 flat field types
 - `MODEL_KINDS` — `singleton`, `collection`, `document`, `dictionary`
-- `MCP_TOOLS` — 17 MCP tool names (includes `contentrain_merge` and `contentrain_doctor`)
+- `MCP_TOOLS` — 19 MCP tool names (includes `contentrain_merge`, branch lifecycle tools, and `contentrain_doctor`)
 - `ESSENTIAL_RULES_FILE` — path to essential guardrails markdown
 - `STACKS` — supported framework stacks
 
@@ -84,7 +84,7 @@ The package root exports constants for tooling:
 ```ts
 import { MCP_TOOLS, ESSENTIAL_RULES_FILE, FIELD_TYPES } from '@contentrain/rules'
 
-console.log(MCP_TOOLS.length)                            // 17
+console.log(MCP_TOOLS.length)                            // 19
 console.log(MCP_TOOLS.includes('contentrain_merge'))     // true
 console.log(MCP_TOOLS.includes('contentrain_doctor'))    // true
 console.log(ESSENTIAL_RULES_FILE)                        // 'essential/contentrain-essentials.md'

packages/skills/README.md

@@ -127,7 +127,7 @@ This reduces always-loaded context from thousands of lines to just the essential
 
 `@contentrain/skills` is kept in lockstep with the MCP tool registry via cross-package parity tests (`tests/mcp-parity.test.ts`):
 
-- `skills/contentrain/references/mcp-tools.md` must have an `### <tool>` heading for every tool in the MCP `TOOL_NAMES` registry (currently 17).
+- `skills/contentrain/references/mcp-tools.md` must have an `### <tool>` heading for every tool in the MCP `TOOL_NAMES` registry (currently 19).
 - Key skills (normalize, translate) must not reference legacy `contentrain/{operation}/...` branch prefixes — MCP now emits `cr/*`.
 
 When MCP's surface changes, these tests fail until the skill docs catch up.