Integrate a Headless CMS with AI Agents Using Claude Code or Codex

Q: Should I fix generated schema types by hand?

Check the CMS schema and run pull instead. Keep application-specific transformations outside files that the CLI regenerates.

To build a CMS integration with an AI coding agent, give it the current documentation, the real content schema, and a specific boundary for changes. With genko.me, a Skill supplies working procedures, llms.txt or MCP supplies reference material, and the CLI generates types from the workspace schema. Review the resulting code and test content delivery, missing content, and draft handling before accepting the integration.

This article is written by the team behind genko.me. It reflects the documentation and SDK and CLI implementation checked on October 20, 2026.

What information does an AI agent need for a CMS integration?

“Connect the CMS” leaves too many choices unspecified. An agent needs to know which application it is changing, which API contains the articles, and whether it should display published content, draft previews, or both.

Start with the existing repository. Its dependency versions, routing structure, generated client, and build scripts are stronger evidence than a framework example recalled by the model.

Information	Example	Mistake it helps prevent
Application structure	Existing dependencies and routes	Unsupported components or runtime assumptions
API and field IDs	Verified `blog`, `title`, `body`	Invented endpoints and property names
Content scope	Published articles or saved draft previews	Exposing drafts in normal delivery
Allowed files	List page and server-side fetching code	Unrelated configuration changes
Acceptance criteria	Typecheck, build, and rendered behavior	Stopping after generating plausible code

If the goal is to write and publish articles rather than application code, start with Claude Code and CMS MCP publishing. The two workflows use some of the same tools but have different outputs and permission needs.

Skills, llms.txt, MCP, and the CLI: which should you use?

These tools solve different parts of the work. They are useful together, but you do not need every one for every task.

Tool	Purpose	Where it operates
Skill	Share setup and maintenance procedures	A project file
llms.txt and Markdown	Read public reference material	Public URLs without authentication
MCP	Search docs and manage workspace content	An OAuth-authenticated connection
CLI	Generate connection files and types; configure AI tooling	Local project and client configuration

A Skill is procedural guidance, not a frozen copy of the complete reference. Use it to establish the sequence of work, then look up parameters and restrictions in the relevant current page. The public documentation does not contain workspace articles or API keys.

Add the genko.me Skill to a project

Preview the supplied instructions from the project root:

bash

npx @genko-me/cli skill --print

To place the file in the project, run:

bash

npx @genko-me/cli skill

The destination is .claude/skills/genko-me/SKILL.md. This is a Claude Code-style location. Do not assume that Codex or another agent automatically reads it. Explicitly ask the agent to read the file, or use that tool's supported loading mechanism.

Running the command again compares the existing file with the template bundled with the CLI. Different contents are replaced. Keep project-specific additions in a separate instruction file so an update does not overwrite them.

A public copy of the Skill is also available when the agent is not using the CLI. Merely installing or reading the Skill does not configure an API key or create CMS content. See the Skill guide for its intended scope.

Give the agent focused documentation through llms.txt

Start with the documentation index, then fetch the pages that apply to the task:

bash

curl 'https://docs.genko.me/en/llms.txt'curl 'https://docs.genko.me/en/sdk/client.md'curl 'https://docs.genko.me/en/sdk/queries.md'

English documentation uses the /en/ prefix. The corresponding Japanese URLs omit it. Individual pages accept a .md suffix, and llms-full.txt provides the complete documentation body.

Fetching the full reference is not always useful. It may exceed an agent's input allowance and can distract from the small set of interfaces being changed. For an article-list implementation, the client and query references are usually more focused starting points than every administration page.

Refresh any saved reference before relying on it. A local copy does not update automatically. The Markdown documentation guide explains the endpoints and their boundaries.

Configure MCP for Claude Code or Codex

If the task benefits from tool-based documentation search or authenticated content operations, choose the command for the client you actually use:

bash

npx @genko-me/cli@latest mcp --claude-code

bash

npx @genko-me/cli@latest mcp --codex

The Claude Code command updates the project's .mcp.json. The Codex command updates the user-wide ~/.codex/config.toml, so it has a broader configuration scope. You do not need to run both commands for one client.

Reload the client, complete OAuth login, and test search_docs followed by get_doc. Building a frontend does not inherently require permission to publish articles. Keep authenticated content operations within the task you have authorized. See the MCP reference for supported operations and permissions.

Sync the schema before generating application code

For a project that has not been connected, prepare the workspace and API key using the quickstart, then initialize the integration:

bash

npx @genko-me/cli init

After a content schema changes in the administration interface, synchronize the local types:

bash

npx @genko-me/cli pull

pull reads the schema; it does not upload articles or translate content. Do not fix a stale field by manually editing a generated schema file. The next synchronization can replace that edit, and the CMS definition would still disagree with the application.

Check genko.config.json for the actual generated paths. A project using src/ or custom output settings may not use the same paths as a minimal example. Reuse the existing generated client where possible.

Keep the delivery API key in server-side environment configuration. The agent does not need its literal value in a conversation, browser bundle, or public repository. The CLI reference describes generated files and synchronization behavior.

A real SDK example for fetching published articles

The following minimal example runs on the server. It assumes a list API named blog, a text field named title, and an API key permitted to read that API. Install the SDK if it is not already present:

bash

npm install @genko-me/sdk

import { createClient } from "@genko-me/sdk";
const apiKey = process.env.GENKO_API_KEY;if (!apiKey) throw new Error("GENKO_API_KEY is required");
const client = createClient({  workspace: "your-workspace",  apiKey,});
const { contents, totalCount } = await client.getList<{ title: string }>({  endpoint: "blog",  queries: { limit: 10, orders: "-publishedAt" },});
console.log(totalCount, contents.map((post) => ({ id: post.id, title: post.title })));

Replace the workspace placeholder with your ID. The generic type describes the expected content; it is not runtime JSON validation. In a normal application, prefer the already generated typed client and handle optional fields according to the actual schema.

Field selection and references require additional care. Selecting fewer fields does not automatically narrow the returned TypeScript type. Reference fields also require checking the actual response shape. Consult the client reference and query guide rather than filling in missing methods from another SDK.

A prompt that produces a reviewable CMS integration

A good prompt defines inputs, scope, and evidence of success:

text

Inspect package.json, routing, genko.config.json, and the generated schema.Read the genko-me Skill and relevant SDK documentation.Reuse the existing client to build a list of published blog articles.Show each title and a link to its detail page.Do not invent APIs, fields, or component props.Do not read or print secret values; use the existing server-side configuration.Handle empty results, fetch failures, and missing articles separately.Run the project's existing typecheck and build, and report failures or skipped checks.Do not write to the CMS, publish content, or deploy the application.

For Next.js display components, ask the agent to check the actual exports and props in @genko-me/react/next. Saved draft previews require the page's searchParams to be passed to View; the SDK does not simply read the page URL on its own.

The prompt is also an opportunity to constrain ambiguous behavior. If a required field is missing, the agent should report the mismatch rather than creating a new content model without approval.

How to verify AI-generated CMS code

Review the integrated diff, imports, and changed files.
Run the application's existing typecheck and build.
Check published content, an empty list, a missing ID, and a delivery failure.
If previews were added, verify that saved drafts remain separate from normal public delivery.
If caching was added, verify update behavior and ensure previews are not placed in shared public caches.

Passing TypeScript does not prove that the server returned every expected value. A selected-out field can still be represented by the broader type, and a referenced entry may not be publicly available. Verify the response and rendered output, not only compilation.

If live CMS access was unavailable, record that limit explicitly. A local mocked response can verify request construction and rendering logic, but it cannot establish that a real workspace, key, or published entry is configured correctly.

For application-specific examples, continue with Next.js and a headless CMS. For language queries and missing translations, use the multilingual CMS guide.

FAQ

Can Codex use the genko.me Skill?

It can work from the Skill's instructions. The CLI writes a Claude Code-style file, so explicitly reference it rather than assuming automatic discovery by Codex.

Can llms.txt update CMS content?

No. It is an entry point to public reference material. Content changes require a separate authenticated interface such as MCP.

Should I fix generated schema types by hand?

Check the CMS schema and run pull instead. Keep application-specific transformations outside files that the CLI regenerates.

Does the CLI pull command change CMS articles?

No. It reads the schema and synchronizes local types. It is not an article upload or migration command.

Sources

Checked October 20, 2026.