MCP server#
plone-client mcp serves one site, or several, to MCP clients, over standard input and output or over HTTP.
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 |
|---|---|
|
Serve the profile |
|
Serve the profiles of the group |
|
Serve every profile. |
|
Refuse changes; see Modes. |
|
Tools that change a site return the requests they would send, and send none. |
|
Offer only the tool |
|
Serve over streamable HTTP instead of standard input and output; see Over HTTP. |
|
Address to listen on, with |
|
Port to listen on, with |
|
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
siteargument, listed first, whose values are the profile names.The
list_sitestool returnsitems, each withname,url,description,read_only, andblocks.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.
Choosing the tools#
Added in version 1.0.0a2.
The model reads the description of every tool the server offers, so a long list costs context in every conversation.
--tool offers only the tools named:
plone-client mcp --profile blog --tool search --tool get_content --tool list_blocks --tool update_block
With several sites, list_sites is offered too.
Protect a site from an agent recommends sets of tools.
Resources#
Added in version 1.0.0a3.
Each site also has read-only resources: data that you, or the application you use, can attach to a conversation. The model calls tools by itself, while how resources are used depends on the application, so they add to the tools and do not replace them.
URI |
Media type |
Description |
|---|---|---|
|
|
The blocks the site offers, with a summary of each. |
|
|
The documentation, data schema and variations of a block. |
|
|
The full JSON of a content item, by its path in the site. |
|
|
The root of the site, as the API serializes it. |
|
|
The content types of the site. |
|
|
The JSON schema of a content type. |
get_content decides whether site and content are offered, content_types decides for types, and block_types decides for blocks.
<site> is the name of the profile, percent-encoded, and site for a server that was built from a client rather than from profiles.
With --tool, a resource is offered only when the tool in the table is, so resources do not widen the access that you chose.
A path with .. in it is refused, and so is a resource of a site that the server does not have.
Resources wait for the same per-site turn as tools.
A name the server would not offer, such as a misspelled tool, or a tool that changes the site when it is read-only, stops the command with exit code 3 before it connects to any site; the error lists the tools it offers.
The server’s instructions are the same whatever the tools, so they may mention tools that are not offered.
Over HTTP#
Added in version 1.0.0a2.
With --http, the server speaks streamable HTTP at http://HOST:PORT/mcp, for assistants that do not start a local command.
The tools, the sites, and the modes are the same as over standard input and output.
Every request needs the header Authorization: Bearer TOKEN, loopback included; without it, or with another token, the server answers 401.
The token is compared in constant time.
plone-client mcp --http reads it from $PLONE_CLIENT_MCP_TOKEN, or else from the keyring, and stops with exit code 3 before connecting to any site when there is none, or when it is shorter than 32 characters.
Command |
Does |
|---|---|
|
Makes a random token, stores it in the keyring, and prints it as |
|
Stores a token of your own, from a hidden prompt or, with |
|
Removes the token from the keyring; prints |
On 127.0.0.1, localhost, and ::1, the server also refuses requests whose Host header names another host (421), which protects against DNS rebinding.
On other addresses, put the server behind a proxy that adds TLS: the token, and the content of the site, would otherwise cross the network in clear text.
The site’s own credentials stay in the server’s profiles. A client of the HTTP server never sees them, and cannot point the server at another site. One server answers every client that has the token, with the same profiles: give each person or team their own server and token when they should not share access.
Tools run one at a time per site, so that operations and block edits from several clients do not mix.
The server writes the address it listens on to standard error, and stops on Ctrl+C or SIGTERM.
Before you deploy the server over HTTP, check each of these.
It listens on the loopback address, or a proxy that adds TLS stands in front of it.
Each person or team that should not share access has its own server and token.
In a container, the token comes from
PLONE_CLIENT_MCP_TOKEN, not from a keyring the container lacks.--tooloffers only the tools the job needs; Protect a site from an agent has sets to start from.Every production site in its profiles is read-only, unless the job is to change it.
You know how to rotate the token:
plone-client mcp-token generatereplaces the one in the keyring, or you set a newPLONE_CLIENT_MCP_TOKEN, which wins; the server reads it only when it starts.
Tools#
The server has 32 tools.
list_sites is offered only with several sites.
The column Read-only site says whether a server of one read-only site offers the tool.
Tool |
Arguments |
Effect |
Read-only site |
Description |
|---|---|---|---|---|
|
|
adds |
no |
Add blocks to an item, keeping the blocks it has. |
|
|
reads |
yes |
The blocks the site offers, or how to write the data of one block. |
|
|
changes |
yes |
Call any |
|
|
changes |
no |
Remove a working copy without applying it. |
|
|
changes |
no |
Apply a working copy to its item, and remove the working copy. |
|
|
adds |
no |
Check out an item into a working copy, to change a published item without changing what visitors see. |
|
|
reads |
yes |
List the content types, or return the field schema of one. |
|
|
adds |
no |
Copy items, with everything inside them, into a folder. |
|
|
adds |
no |
Create one content item with the given field values. |
|
|
adds |
no |
Create an item, upload files and images inside it, and set its lead image. |
|
|
adds |
no |
Create a page from Markdown or HTML, converted to Volto blocks. |
|
|
changes |
no |
Delete content items, and everything inside them. |
|
|
reads |
yes |
Read one content item: its fields, blocks and workflow state. |
|
|
reads |
yes |
The navigation tree of the site, to find where content lives. |
|
|
reads |
yes |
The translations linked to an item, with their language. |
|
|
reads |
yes |
The valid values of a choice field: the terms of a vocabulary. |
|
|
reads |
yes |
The workflow state of an item and the transitions it can run now. |
|
|
reads |
yes |
The working copy of an item, or the item a working copy belongs to. |
|
|
adds |
no |
Link an existing item as a translation of another. |
|
|
reads |
yes |
The blocks of an item, in order: id, type and the start of their text, with the blocks inside containers. |
|
|
reads |
yes |
List the items directly inside a folder, in the folder’s order. |
|
— |
reads |
yes |
The sites this server works on: name, URL, description, and whether changes to it are refused. |
|
|
changes |
no |
Move items, with everything inside them, into a folder. |
|
|
changes |
no |
Remove blocks from an item, with any blocks inside them. |
|
|
changes |
no |
Run a workflow transition, such as publish, on a content item. |
|
|
reads |
yes |
Search the catalog of the site, inside a folder. |
|
|
changes, repeatable |
no |
Replace all the blocks of an item. |
|
— |
reads |
yes |
The site, the user the server is logged in as, and its mode. |
|
|
changes |
no |
Remove the link to the translation in a language; both items stay. |
|
|
changes, repeatable |
no |
Change the data of one block, also inside a container. |
|
|
changes, repeatable |
no |
Change field values of a content item; other fields are kept. |
|
|
adds |
no |
Upload a local folder: subfolders become pages, files become File and Image items, keeping the structure. |
A ? marks an optional argument.
With several sites, every tool but list_sites also takes a required site.
The column Effect comes from the tool’s annotations: reads, adds (destructiveHint: false), changes (destructiveHint), and changes, repeatable (destructiveHint, idempotentHint).
A client should not retry a tool that is only changes: running it twice does not give the same result.
create_page is offered only when collective.html2blocks is installed.
get_translations needs plone.app.multilingual, and get_working_copy needs plone.app.iterate.
create_content_with_files, create_page, and upload_tree read local paths on the computer of the server.
call_service is offered in every mode, and follows the server’s read-only and dry run settings like any other request.
The blocks argument of create_page and upload_tree chooses the block types that Markdown and HTML become, merged over the blocks setting of the site’s profile; see Block types of converted pages.
When a site has such a setting, the server’s instructions state it.
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.
Blocks#
Added in version 1.0.0a2.
The tools that take blocks take them as a list, in order, each with an @type.
The server gives them ids and builds the layout, and goes through normalize(): a string href becomes a list of links, and a container such as a gridBlock can list its own blocks the same way.
[
{"@type": "slate", "plaintext": "Latest news"},
{
"@type": "gridBlock",
"blocks": [
{"@type": "teaser", "href": "/news/first"},
{"@type": "teaser", "href": "/news/second"}
]
}
]
create_content and update_content accept such a list as data["blocks"] too, through prepare().
A mapping of block ids also works; its layout is then tidied with tidy().
A block without @type is refused with ValueError before any request is sent.
add_blocks, update_block, remove_blocks, and set_blocks read the item, change its blocks, and save them with one PATCH.
They work on blocks inside containers too, and return an outline of the saved blocks in item.blocks.
They take no lock, so a change someone else saves between the read and the write is lost.
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 |
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 change is sent; it can read from the site first.
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. When the credentials of a site were rejected, the instructions warn about it and name the fix.
The instructions of every server
Work with the content of Plone 6 sites through plone.restapi.
Paths are site paths such as /news/my-item; the @id URLs that tools return
work too. Read the @id of what a tool creates: Plone may change the id that
was asked for.
Content model, mostly for sites with the Volto frontend:
- The text of a page is in its blocks: `blocks` maps block ids to block
data and `blocks_layout.items` lists them in order; a page without both
shows nothing. Use `block_types` to learn which blocks the site has and
the data each one takes. To write prose, prefer `create_page`, which
converts Markdown to blocks.
- Wherever a tool takes blocks, give them as a list in order, each with an
`@type`; ids and the layout are made for you, and a container such as a
gridBlock may list its own `blocks` the same way. To change a page,
`list_blocks` shows its block ids; then `add_blocks`, `update_block` and
`remove_blocks` change only those blocks.
- Folder usually cannot be added, even though `content_types` lists it. For a
section such as /news, create a Document (Page): it is folderish, and so is
News Item. `content_types` with `addable_in` lists what a folder can hold,
and a dry run adds a `warning` to an item the site would refuse.
- A News Item has no `image` field: its lead image is `preview_image_link`, a
relation to an Image stored inside it. Use `create_content_with_files`.
- Fields a type does not have are silently ignored. Check the schema with
`content_types` before setting unusual fields.
- New items are private until a workflow transition such as `publish` runs.
Changes are refused when the server is read-only, and a site that lists
`transitions` in list_sites runs only those workflow transitions. In a dry
run, nothing is changed: tools return the requests they would have sent,
with a `warning` when the site would refuse or ignore part of them.
Rejected credentials#
Added in version 1.0.0a2.
Plone answers a wrong password as an anonymous request, so reads still work and only changes fail.
When a site is configured with a username or token and answers as anonymous, plone-client mcp checks each site at startup and writes a warning to standard error: the server still starts.
The same warning is in the instructions, and site_info reports credentials_rejected.
A site with no username or token that answers as anonymous is not reported.
Fix the secret with plone-client profile set-secret NAME.
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.