You're reading docs for Nextly Alpha. APIs may change between releases.

Plugins

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-mcp and 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-mcp
import { 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.

ToolWritesInputAnswer (structuredContent)
get_initial_contextNonone{ entities, complete }: what the key may read
get_workflowNo{ collection } or { single }{ workflow }: its stages and steps, or null
get_review_stateNo{ document }{ workflow, parts }: each part's stage and steps
list_waiting_for_reviewNo{ page?, limit? }{ items, meta }: what waits for the key, a page at a time
submit_for_reviewYes{ 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's revision and version, as get_review_state gave them. A part that moved since is refused with 409 CONFLICT (data.reason: "stale"): read it again before deciding.
  • comment: required, and more than blanks.
  • step: a step of kind submit. 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.

CodeStatusWhen
WORKFLOW_STEP_NOT_SUBMIT400step names a step that is not a submit, such as an approval or a move.
WORKFLOW_NO_SUBMIT_STEP409No step is named, and no submit step leaves the stage a part stands in.
VALIDATION_ERROR400With WORKFLOW_STEP_REQUIRED in data.errors: more than one submit step could be meant.
FORBIDDEN403The key does not hold the step's permission, such as update-posts.
NOT_FOUND404The 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.