Skip to content

Build a content model with an agent

The ebitex team
A chat request with a star beside it flows into a hexagon labelled MCP, which turns it into three stacked Contract cards; a key sits below, labelled one key, one environment.

There is now an MCP server for ebitex Content. Point an AI agent at it and it can do the work you would otherwise do in Composer: design Contracts, add fields to them, create Templates, write Components, give them addresses in the Experience tree, and publish the lot.

It is one npx line and a key you mint yourself. What follows is how to set that up without handing an agent more reach than you meant to — and then the more interesting half, which is what it turns out to be good at.

What it is, and what it is not

It is a local server. It runs on your machine over stdio, and nothing about it is hosted by us. That is deliberate rather than incidental: hosting it would mean holding customers’ write-capable keys and sitting in the path of every authoring request, for no capability anyone would gain.

It is also only the write side. It has no browser, no file reader, no screenshot tool. When this post says "point it at a Storybook library", it is the agent that reads the library, using whatever tools it already has; the server is what turns the conclusion into Contracts. Worth being clear about, because it decides where the work actually happens. Your agent’s judgement about your content is the interesting part. This is the part that stops it having to guess at HTTP.

And it knows nothing about the content model. It holds a table of which URL each kind of thing lives at, and that is genuinely the whole of it — what field types exist, what a Contract may contain, what makes a document valid are all answered at runtime by the server that stores them. There is a test in the package that greps its own built output for field-type names and fails if one appears. The point of that is not tidiness: it means there is no second copy of the model sitting here to fall out of step with the product.

Mint a key, deliberately

Everything an agent can do here, it can do because of one credential. So it is worth a minute rather than a few seconds.

Management keys need the Pro plan or above. A trial counts, so you can try this today. They live in Content under Settings → API Keys → Management keys.

Four things are fixed the moment you create one, and none of them can be widened afterwards.

Its environment. A key works in one authoring environment and no other. The page binds it to whichever environment the switcher at the top is currently showing, so check that first — it is the one field on the form that is not a field on the form.

Its role. The key acts as exactly the role you give it: the same folder permissions, the same approval workflows, the same limits. A key bound to a role that cannot edit a folder cannot edit that folder, and a page waiting for approval cannot be published by a script any more than by a person. Pick the least powerful role that can do the job.

Its permissions. Four of them, and they combine:

PermissionLets the key
ReadLook at what is there, and preview what a change would do
WriteApply a whole bundle of changes at once, and upload files
PublishMake content live
AuthoringCreate, edit and delete individual items — a Contract, a Component, a page

Authoring is the only one that can delete anything, which is exactly why it is separate from Write rather than part of it. Write applies a bundle, and a bundle only ever adds or updates. So a key that has quietly worked for your pipeline for months keeps doing precisely what it always did; nothing widens on its own because a new capability shipped.

Its IP ranges, optionally. If the agent runs somewhere with a fixed address, this is worth the thirty seconds.

Then there is the part the server cannot help with, and says so. It has no way to tell which of your environments is production. That is your own topology, expressed in delivery mappings a management key deliberately cannot see. A name heuristic — refuse anything containing prod — would be worse than nothing, because it would be believed. So the protection is the credential, and it is real: mint against a scratch or staging environment, and leave Authoring off unless the agent actually needs to write.

That last one has a nicer consequence than it sounds. A key without the authoring scope produces a server whose write tools are absent, not present-and-failing. An agent cannot keep trying a tool it cannot see, which is a much better thing to hand it than one that refuses every time.

The key is shown once. Copy it into your secret store before closing the dialog.

Wire it up

Wherever your MCP client keeps its server list:

{
  "mcpServers": {
    "ebitex-content": {
      "command": "npx",
      "args": ["-y", "@ebitex/content-mcp"],
      "env": { "EBITEX_CONTENT_MANAGEMENT_KEY": "frm_live_..." }
    }
  }
}

On startup it prints what the key actually reached:

ebitex Content MCP
  api           https://api.ebitex.io
  organization  Northwind Coffee
  environment   Scratch
  acting as     Editor  (key: agent-scratch)
  scopes        content.management.authoring, content.management.publish, …
  mode          READ-WRITE — writes land in "Scratch"

Read it once. If the environment on that third line is not the one you meant, stop — nothing else in the session is going to tell you. A management key is an opaque string, and until recently everything about it was resolved on every request and then told to nobody. That banner exists for exactly one failure, and it is not a bug in any of this: a key bound to the wrong environment sitting in a config file, and an agent doing exactly what it was asked to.

Three other environment variables are worth knowing:

Variable
EBITEX_CONTENT_API_BASEDefaults to https://api.ebitex.io
EBITEX_CONTENT_MCP_READ_ONLYSet to 1 to hide every write tool, whatever the key holds
EBITEX_CONTENT_TARGET_MANAGEMENT_KEYA second key, for moving a finished model into another environment

What to point it at

The three starting points below all end in the same place: a set of Contracts, a set of Templates, and an opinion about which is which. That last part is where an agent needs the most steering, so it is worth saying the rule plainly before any of them.

A Contract says what content is. A Template says how it looks. If you find yourself adding a field called variant, align, theme, columns or size to a Contract, it almost certainly belongs in a Template’s settings instead. Getting that one line in the right place is most of what separates a model you can reuse from a pile of page-shaped types that each work exactly once.

An existing web page

The obvious starting point, and the one with the sharpest trap. Give an agent a URL and it will cheerfully produce a HomePage Contract with heroTitle, heroSubtitle, feature1Title, feature1Body, and so on down the page. Everything will validate. Everything will render. None of it will be reusable, and the second page will arrive with its own Contract carrying the same fields under different names.

The question that avoids all of it is not "model this page" but "what kinds of thing are on this page?" A product. A testimonial. A person. A navigation link. Those are the Contracts. The page itself is then a thin Contract whose fields hold presentation values pointing at them — which is also what makes the third page cost almost nothing.

In practice the most useful thing you can do is ask for that list before anything is written: the Contracts it proposes, one line of justification each, and no writes. It is far cheaper to argue about a list than to un-create twelve Contracts. Then let it build.

Two habits worth insisting on while it does. It should call content_describe first, which answers what this environment already has, and content_find before creating anything — because a duplicate external id is a lasting problem rather than a tidy-up. External ids are how a model refers to itself across environments.

A design

Here the trap is inverted. A design file is almost entirely presentation, so everything in it looks like a Template and the content underneath goes unnamed. An agent working from one will happily give you twelve Templates and three anaemic Contracts.

The question that helps: which boxes in this design are the same box with different words in it? That pairing — one repeated box, many sets of words — is a Template and a Contract, and once you have named a few the rest of the design tends to sort itself.

A design also gives you something a live page never does. The variants a designer has already drawn — primary and secondary, two columns and three, with an image and without — are not properties to be inferred from examples. They are an enumerated list, decided by somebody, and they map directly onto a settings field with allowedValues. That is the real gift of working from a design rather than a rendered page: the closed sets arrive already closed.

A Storybook component library

The best of the three by some margin, because most of the work is already done and it is already machine-readable.

A Storybook story is a component plus its argTypes: a declared, typed, enumerated list of every prop it takes and every legal value. A Template’s settings are an ordinary Contract describing the presentational choices that Template offers. Those two things are very nearly the same document written twice, and translating between them is exactly the kind of work an agent is reliably good at.

In StorybookIn Content
A componentA Template
Its content-bearing props — text, images, listsThe Contract that Template renders
Its presentational props — variant, size, alignFields on that Template’s settings Contract
A prop’s union type, or argTypes.optionsallowedValues on that settings field
An array propOne field, isEnumerable
children, or a slotA presentation field
A prop that is another component’s propsA component field

One row of that table is worth pulling out, because it is the thing an agent most reliably gets wrong on its first attempt: cardinality is a modifier’s job, never the field type’s. There is no "list of text" field type. There is a text field that is enumerable. An agent that has not read that will invent textList, be refused, read the error and correct itself — which works, and costs a round trip per field, so it is worth saying up front.

What makes a component library genuinely the best input rather than merely a convenient one is not the format. It is that the names in it already mean the same thing to the design team and the engineering team. A model derived from it comes out speaking vocabulary both of them already recognise, which is a problem content modelling normally has to solve by committee.

Seeding the content

Once the Contracts exist, filling them is the easy half — and it is the half where plausible is the risk. An agent writes fluent placeholder copy that reads like somebody signed it off. Seed it, then read it. That is the whole warning, and it is a real one.

Mechanically, three things decide whether the first attempt lands.

Modifiers change the shape of the value, not just the rules about it. A field’s value depends on its type and on what is switched on. Localizable makes it { default, translations }. Personalizable makes it { default, variants }. Enumerable makes it a list. An agent that sends a bare string to a localizable field gets a validation error naming that field — which brings us to the part that makes all of this work.

A refusal is the control loop. Errors come back whole, with every field path intact, never summarized and never elided. That is deliberate to the point of deciding the architecture: it is why this server drives the per-entity API for authoring rather than bundles, because a per-entity write refuses one document with its failing field named, where a bundle import refuses a bundle. The loop is try, read the error, fix the one thing it names, call again — and it converges quickly precisely because nothing removed the field the next call had to set.

It looks like this, and the third step is the design working:

→ content_write  kind: component
   { contractId: "…", externalId: "welcome", name: "Welcome", document: {} }
← HTTP 400 validation_failed
  { "errors": { "headline": "This field is required." } }

→ content_write  kind: component
   { …, document: { headline: "Welcome" } }
← { id: "…" }

Order matters in one direction only. A Component that references another needs that one to exist first; a Contract that names a parent needs the parent first; a Template needs the Contracts it renders. Nothing else does. Build outward from the things that depend on nothing and you will never be waiting on something that is not there yet.

One more habit worth asking for, because an agent will often skip it: content_describe returns every field type with its own settings JSON Schema, generated from that field type’s own definition. Content’s Contract builder renders its settings form from exactly the same thing rather than hard-coding a form per type. There are fifteen field types today, five of them deprecated, and the server will tell you which — so there is nothing here worth guessing at.

Publishing

Publishing is two calls, and collapsing them into one would hide the thing that matters.

Plan resolves the full dependency closure of whatever you asked to publish, and reports every blocker: an unresolvable reference, a workflow state that forbids publishing, a document that no longer validates. Execute publishes what the plan named.

Read the plan. It is the only place the system tells you what is about to change beyond what you actually named — publishing a page normally publishes the content it binds, and whatever that binds, and the plan is where you see how far it reaches before it happens rather than afterwards. Both calls are jobs: each returns an operation id you poll, because a real closure does not finish inside an HTTP request.

One shape detail bites hard enough to be worth a sentence. Pass the plan’s own items back to execute. Sending a bare {kind, id} leaves include unset, which counts as skip — so the job answers succeeded having published nothing at all, which is a genuinely difficult failure to notice. To leave something out, set include: false on it rather than dropping it from the list.

The thing it cannot undo

There is no unpublish. Not in this server, and not in the API underneath it — v1 deliberately has none, so content_delete on a published node or Component answers 409 node_published, and nothing here can clear that. Taking something down is a Composer action, by a person.

That asymmetry is worth knowing before an agent starts publishing exploratory work, and it is the strongest argument for the scratch environment: an agent can create and publish, and it cannot fully clean up after itself.

Where to start

Start read-only. Mint a key with Read alone, or set EBITEX_CONTENT_MCP_READ_ONLY=1, and ask the agent to describe your environment and propose a model as a list. No writes, nothing to undo — and you will learn more from the list it produces than from anything it would have built.

Then give it a scratch environment and let it actually build. That is where it gets interesting, and where a bad idea costs nothing. Promote what survives.

npx -y @ebitex/content-mcp — the package README has the configuration, the full tool list, and the rest of what this post skipped.

The key that published this post was minted for it, bound to one environment with an expiry, used once, and revoked. The publish itself went through content_publish.