MCP
A Model Context Protocol endpoint for AI agents, off by default, that reads review state and submits for review as the key it is given, and approves and publishes nothing.
Experimental: pin your versions.
@nextlyhq/plugin-mcpand the tools it serves are experimental. Their names, inputs and answers may change between alpha releases. Pin your versions and read the release notes before upgrading.
The MCP plugin serves a Model Context Protocol endpoint, so an AI agent can learn what an install lets it read, read where documents stand in review, and submit its work for a person to review.
It is off by default, and authenticated like every other Nextly route: an agent connects with an API key, and every tool answers for that key, judged on the grants stamped on the key and never on the roles of whoever minted it. An agent is bounded by the key you give it.
Installation
npm install @nextlyhq/plugin-mcpimport { mcpPlugin } from "@nextlyhq/plugin-mcp";
import { defineConfig } from "nextly/config";
export default defineConfig({
plugins: [mcpPlugin({ enabled: true })],
});While enabled is false, the default, the plugin contributes no route at all. Turned on, the
endpoint answers at /admin/api/mcp in a scaffolded project (pass path to move it), on the
hostname of NEXT_PUBLIC_APP_URL unless you name allowedHosts. The package README covers the
address checks and the protocol revisions it serves.
The tools
Five tools. Four read, and exactly one writes: submit_for_review.
Every answer carries a constant sentence as its text and the data as structuredContent. Text
people wrote, such as a comment, a title or a stage's label, is never put into the sentence: it
arrives only as data, so it cannot pose as an instruction to the agent.
| Tool | Writes | Input | Answer (structuredContent) |
|---|---|---|---|
get_initial_context | No | none | { entities, complete }: what the key may read |
get_workflow | No | { collection } or { single } | { workflow }: its stages and steps, or null |
get_review_state | No | { document } | { workflow, parts }: each part's stage and steps |
list_waiting_for_review | No | { page?, limit? } | { items, meta }: what waits for the key, a page at a time |
submit_for_review | Yes | { document, parts, seen, comment, step? } | { step, moved, left, reviewer, skippedReviewer } |
A document is { "collection": "posts", "id": "…" } for an entry and { "single": "homepage" }
for a Single. Every input is strict: a key a tool does not name is refused, not ignored.
get_workflow
The review workflow attached to a collection or Single: its stages in order and the steps
between them, each with its kind (submit, approve, request-changes or move), the stages it
leaves from and the one it enters. Never the workflow's settings, who may take its steps, or the
other collections and Singles it is attached to. Name exactly one of collection and single.
get_review_state
Where a document stands, part by part: each language is a part, and so is the content every
language shares (part: null). Each part carries its stage, whether it may be published, who it
waits for, its last move, and each step out of its stage with mayTake, whether this key may take
it. It also carries revision and version: what a submit must say it saw. The fields are those
of the REST route's review state.
list_waiting_for_review
The parts assigned to the key's owner, in stages whose step the key may take, in documents it may
read, as a list envelope: { items, meta }. page starts at 1, and limit is 1 to 100 (20 unless
named).
submit_for_review
Submits parts of a document for review, with a comment the reviewer reads:
{
"document": { "collection": "posts", "id": "…" },
"parts": ["es"],
"seen": [{ "part": "es", "revision": 0, "version": "…" }],
"comment": "Translated; ready for legal"
}parts: each part named. There is no "every part": an agent says which it worked on.seen: each part'srevisionandversion, asget_review_stategave them. A part that moved since is refused with409 CONFLICT(data.reason: "stale"): read it again before deciding.comment: required, and more than blanks.step: a step of kindsubmit. Left out, the submit step out of the parts' stage is taken.
A submit approves nothing: a submitted part is not made publishable by it, and a person still reviews it. The history names the key that submitted, by its own id.
What an agent cannot do
No tool approves, requests changes, publishes, publishes without review, assigns, or changes a
workflow, and no tool takes an argument that would. An approval is a person's to give: an API key
may never approve or request changes, whatever grants it holds, and submit_for_review refuses
any step that is not a submit.
| Code | Status | When |
|---|---|---|
WORKFLOW_STEP_NOT_SUBMIT | 400 | step names a step that is not a submit, such as an approval or a move. |
WORKFLOW_NO_SUBMIT_STEP | 409 | No step is named, and no submit step leaves the stage a part stands in. |
VALIDATION_ERROR | 400 | With WORKFLOW_STEP_REQUIRED in data.errors: more than one submit step could be meant. |
FORBIDDEN | 403 | The key does not hold the step's permission, such as update-posts. |
NOT_FOUND | 404 | The key may not read the document, or not in a part it named. |
A refusal answers with isError: true and the error as structuredContent.error: the same
{ code, message, requestId, data? } the REST routes send. A failure that is not a deliberate
refusal answers with one fixed sentence and INTERNAL_ERROR, never the failure's own message;
the server's log has the detail under the requestId.
One language at a time
A document's languages are reviewed separately, and a key is held to each one. Where a
collection's read rule refuses a language (say read: ({ locale }) => locale !== "es"), a key is
told nothing of that language's part: get_review_state leaves it out, list_waiting_for_review
does not list it, and submit_for_review answers a part in it as 404 NOT_FOUND, exactly as
though the document had no such part. The other languages of the same document answer as
usual.
SEO
An SEO tab and field group on every collection and Single, every page's head, and the site's sitemap and robots.txt.
Commerce
A catalogue to sell from, a cart kept on the server behind a cookie, and a checkout that turns it into an order and starts its payment, with the REST routes and typed server functions a storefront uses.