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

--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.

--tool NAME

Offer only the tool NAME. Repeat it for several; see Choosing the tools.

--http

Serve over streamable HTTP instead of standard input and output; see Over HTTP.

--host HOST

Address to listen on, with --http. Default 127.0.0.1.

--port PORT

Port to listen on, with --http. Default 8000.

-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, read_only, and blocks.

  • 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

plone://site/blocks

text/markdown

The blocks the site offers, with a summary of each.

plone://site/blocks/{block_id}

text/markdown

The documentation, data schema and variations of a block.

plone://site/content/{+path}

application/json

The full JSON of a content item, by its path in the site.

plone://site/site

application/json

The root of the site, as the API serializes it.

plone://site/types

application/json

The content types of the site.

plone://site/types/{portal_type}

application/json

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

plone-client mcp-token generate

Makes a random token, stores it in the keyring, and prints it as token. A token stored before is replaced.

plone-client mcp-token set

Stores a token of your own, from a hidden prompt or, with --token-stdin, from standard input.

plone-client mcp-token delete

Removes the token from the keyring; prints deleted.

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.

  • --tool offers 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 generate replaces the one in the keyring, or you set a new PLONE_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

add_blocks

path, items (list), after?, position?

adds

no

Add blocks to an item, keeping the blocks it has.

block_types

block_id?, path?

reads

yes

The blocks the site offers, or how to write the data of one block.

call_service

method, path, params?, body?

changes

yes

Call any plone.restapi service that no other tool covers.

cancel_working_copy

path

changes

no

Remove a working copy without applying it.

check_in

path

changes

no

Apply a working copy to its item, and remove the working copy.

check_out

path

adds

no

Check out an item into a working copy, to change a published item without changing what visitors see.

content_types

portal_type?, addable_in?

reads

yes

List the content types, or return the field schema of one.

copy_content

sources (list), target

adds

no

Copy items, with everything inside them, into a folder.

create_content

parent, portal_type, data?, publish?

adds

no

Create one content item with the given field values.

create_content_with_files

parent, portal_type, files (list), data?, lead_image?, publish?

adds

no

Create an item, upload files and images inside it, and set its lead image.

create_page

parent, source, source_format?, portal_type?, title?, description?, data?, files? (list), lead_image?, publish?, blocks?

adds

no

Create a page from Markdown or HTML, converted to Volto blocks.

delete_content

paths (list)

changes

no

Delete content items, and everything inside them.

get_content

path?, fields? (list), expand? (list)

reads

yes

Read one content item: its fields, blocks and workflow state.

get_navigation

path?, depth?

reads

yes

The navigation tree of the site, to find where content lives.

get_translations

path

reads

yes

The translations linked to an item, with their language.

get_vocabulary

vocabulary?, path?, title?, limit?

reads

yes

The valid values of a choice field: the terms of a vocabulary.

get_workflow

path

reads

yes

The workflow state of an item and the transitions it can run now.

get_working_copy

path

reads

yes

The working copy of an item, or the item a working copy belongs to.

link_translation

path, translation

adds

no

Link an existing item as a translation of another.

list_blocks

path

reads

yes

The blocks of an item, in order: id, type and the start of their text, with the blocks inside containers.

list_children

path?, portal_type? (list), limit?

reads

yes

List the items directly inside a folder, in the folder’s order.

list_sites

—

reads

yes

The sites this server works on: name, URL, description, and whether changes to it are refused.

move_content

sources (list), target

changes

no

Move items, with everything inside them, into a folder.

remove_blocks

path, block_ids (list)

changes

no

Remove blocks from an item, with any blocks inside them.

run_transition

path, transition, comment?, include_children?

changes

no

Run a workflow transition, such as publish, on a content item.

search

path?, text?, portal_type? (list), review_state? (list), depth?, query?, sort_on?, descending?, limit?

reads

yes

Search the catalog of the site, inside a folder.

set_blocks

path, items (list)

changes, repeatable

no

Replace all the blocks of an item.

site_info

—

reads

yes

The site, the user the server is logged in as, and its mode.

unlink_translation

path, language

changes

no

Remove the link to the translation in a language; both items stay.

update_block

path, block_id, data, replace?

changes, repeatable

no

Change the data of one block, also inside a container.

update_content

path, data

changes, repeatable

no

Change field values of a content item; other fields are kept.

upload_tree

local_path, parent, convert_pages?, publish?, blocks?

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 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 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.