MCP server

MCP server#

plone-client mcp serves one site, or several, to MCP clients over standard input and output. It needs the mcp extra, which adds the official MCP Python SDK.

Command#

plone-client mcp --profile blog
plone-client mcp --site blog --site docs
plone-client mcp --group customer
plone-client mcp --all

Without --site, --group, or --all, the server serves one site, and takes its connection from the same places as every other command: --profile, $PLONE_CLIENT_PROFILE, .plone-client.toml, the current profile, or --url with the PLONE_CLIENT_* variables.

Option	Effect
`--site NAME`	Serve the profile `NAME`. Repeat it for several sites.
`--group NAME`	Serve the profiles of the group `NAME`; see Groups. Repeatable.
`--all`	Serve every profile.
`--read-only`, or a profile with `read_only = true`	Refuse changes; see Modes.
`-n`, `--dry-run`	Tools that change a site return the requests they would send, and send none.
`-v`, `--verbose`	Log each request to standard error.

--site, --group, and --all combine, and each profile is served once: every profile for --all, then the --site profiles, then the profiles of each group. They cannot be combined with --profile or --url; the command exits with code 3. --read-only, --dry-run, and --verbose apply to every site. --read-only must come before mcp. Without the mcp extra, the command exits with code 3.

Several sites#

With more than one site, the server changes as follows.

Every tool has a required site argument, listed first, whose values are the profile names.
The list_sites tool returns items, each with name, url, description, and read_only.
The server’s instructions list the sites with their URL, description, and whether they are read-only.
Each site has its own client, created the first time a tool uses that site. A profile whose secret is missing fails only when a tool uses it.

With one site, from --site or otherwise, tools have no site argument and there is no list_sites.

Tools that read#

Tool	Arguments	Returns
`site_info`	none	URL, `frontend_url`, whether the server is logged in and as whom, `read_only`, `dry_run`, and the Plone version.
`get_content`	`path`, `fields`, `expand`	One item, without the items it contains; only the keys in `fields`, when given.
`list_children`	`path`, `portal_type`, `limit` (1–500, default 50)	`items` inside a folder, in the folder’s order, and `items_count`.
`search`	`path`, `text`, `portal_type`, `review_state`, `depth`, `query`, `sort_on`, `descending`, `limit` (1–500, default 25)	`items` found and `items_count`. `query` holds any other catalog index.
`get_navigation`	`path`, `depth` (1–5, default 2)	The navigation tree.
`content_types`	`portal_type`, `addable_in`	The content types, or the JSON schema of `portal_type`.
`block_types`	`block_id`, `path`	Markdown: the blocks of the site, or the docs, schema, and variations of one block; see Block types.
`call_service`	`method`, `path`, `params`, `body`	`status` and `body` of any `plone.restapi` request.

call_service is offered in every mode, and follows the server’s read-only and dry run settings like any other request.

Tools that change the site#

Tool	Arguments	Does
`create_content`	`parent`, `portal_type`, `data`, `publish`	Create one item; returns its summary.
`update_content`	`path`, `data`	Change fields of an item.
`run_transition`	`path`, `transition`, `comment`, `include_children`	Run a workflow transition.
`delete_content`	`paths`	Delete items.
`create_content_with_files`	`parent`, `portal_type`, `files`, `data`, `lead_image`, `publish`	`create_with_files()`; `files` are local paths.
`create_page`	`parent`, `source`, `source_format`, `title`, `description`, `data`, `publish`	`create_page()`. Offered only when `collective.html2blocks` is installed.
`upload_tree`	`local_path`, `parent`, `convert_pages`, `publish`	`upload_tree()`.
`copy_content`	`sources`, `target`	`copy_items()`.
`move_content`	`sources`, `target`	`move_items()`.

The tools that run an operation return its OperationResult as JSON. Paths are site paths such as /news/item; the @id URLs that tools return work too.

Tool annotations#

Annotation	Tools
`readOnlyHint`	`list_sites`, and the tools that read, except `call_service`.
`destructiveHint: false`	`create_content`, `create_content_with_files`, `create_page`, `upload_tree`, `copy_content`.
`destructiveHint`, `idempotentHint`	`update_content`, `run_transition`, `move_content`, `call_service`.
`destructiveHint`	`delete_content`.

Modes#

Mode	Tools offered	Requests that change the site
Default	All	Sent.
Dry run	All	Recorded and skipped; tools return what would be sent.
Read-only	The tools that read	Refused with `PloneReadOnlyError`.

Read-only applies per site: a site is read-only with --read-only or when its profile has read_only = true. The tools that change a site are offered when at least one site is not read-only. A tool that would change a read-only site is refused with PloneReadOnlyError before any request is sent.

The server’s instructions, which MCP clients pass to the model, describe the Volto content model and say which sites are read-only and whether the server is in a dry run.

Errors#

A tool that fails returns an error result whose text is the same JSON the command line prints on standard error: error with type, message, and, for errors answered by the site, status_code, method, and url. An operation that stops part way also returns result, with what it had done. ValueError and OSError, such as a missing local file, return error with their type and message.