Connect an assistant through the MCP server#

This guide shows you how to give an assistant, or any other client of the MCP, access to a Plone site through the plone-client MCP server.

An MCP client needs one of two things.

  • For a server on your computer, a command to start, which speaks over standard input and output: plone-client mcp --profile blog.

  • For a server somewhere else, a URL and a token.

The rest of this guide sets those up, and shows where each client keeps them.

Install the server#

Install plone-client as a tool with the mcp extra. Add the markdown extra too, on Python 3.12 or later, so the assistant can write pages in Markdown.

uv tool install "plone-client[mcp,markdown]"
pipx install "plone-client[mcp,markdown]"

To skip the installation, a client can start the server with uvx. Use uvx as the command, and --from, plone-client[mcp], plone-client, mcp, --profile, and blog as its arguments. The first start takes longer, and the profile still has to exist, so you need the cli extra once to create it.

Add a profile for the site#

The server connects with a profile, so the password stays in the keyring and never reaches the assistant.

plone-client profile add blog --url https://example.org --username editor
plone-client profile test blog

To keep the assistant from changing anything, make the profile read-only.

plone-client profile add blog-ro --url https://example.org --username editor --read-only

If the profile’s URL is the backend rather than the Volto frontend, add the URL of the frontend, so the assistant can learn the site’s blocks.

plone-client profile add local --url http://localhost:8080/Plone --username admin --frontend-url http://localhost:3000

Refer to Manage profiles for the other ways to keep a secret.

Register the server with your client#

The JSON entry below is the same for most clients; only the file and, in places, the key differ.

Add the server to the current project.

claude mcp add plone-blog -- plone-client mcp --profile blog

Pass --scope user to make it available in every project, or --scope project to share it with the project’s other contributors in .mcp.json.

Connect Claude Desktop to a Plone site goes through every step, from the installation to the first question.

Add the server to .cursor/mcp.json in the project, or to ~/.cursor/mcp.json for every project.

{
  "mcpServers": {
    "plone-blog": {
      "type": "stdio",
      "command": "plone-client",
      "args": ["mcp", "--profile", "blog"]
    }
  }
}

Add the server to .vscode/mcp.json in the project. The top-level key is servers, not mcpServers.

{
  "servers": {
    "plone-blog": {
      "type": "stdio",
      "command": "plone-client",
      "args": ["mcp", "--profile", "blog"]
    }
  }
}

Add the server with the command.

codex mcp add plone-blog -- plone-client mcp --profile blog

Or write it to ~/.codex/config.toml, or to .codex/config.toml in a trusted project.

[mcp_servers.plone-blog]
command = "plone-client"
args = ["mcp", "--profile", "blog"]

Add the server to .gemini/settings.json in the project, or to ~/.gemini/settings.json for every project.

{
  "mcpServers": {
    "plone-blog": {
      "command": "plone-client",
      "args": ["mcp", "--profile", "blog"]
    }
  }
}

Most clients read this shape, under some name, from an mcp.json file.

{
  "mcpServers": {
    "plone-blog": {
      "command": "plone-client",
      "args": ["mcp", "--profile", "blog"]
    }
  }
}

If yours takes something else, it needs the same two things: the command plone-client, and the arguments mcp, --profile, and blog.

Your own Python program is a client too. Connect from Python shows how it connects.

Check the connection#

Ask the assistant to call the site_info tool. It reports the site, the user the server is logged in as, and whether it is read-only or in a dry run.

Serve several sites from one server#

If you work with several sites, register one server for all of them rather than one server per site. Add a profile for each site first, with a description that says what the site is, because the assistant reads it to pick the site.

plone-client profile add docs --url https://docs.example.org --username editor --description "Documentation, production"

Name the profiles with --site, or serve every profile with --all. In the arguments of the entry you registered, write them instead of --profile.

plone-client mcp --site blog --site docs

To serve the same set of sites from several places, save them as a group, and serve the group.

plone-client profile group-set customer blog docs
plone-client mcp --group customer

A site added to the group later is served the next time the assistant starts the server. Each tool then takes a site argument, and the list_sites tool describes the sites. A read-only profile stays read-only: the server refuses to change that site, and still changes the others. Build an editorial assistant builds this setup, step by step.

Preview changes first#

To see what the assistant would change without changing anything, add --dry-run to the arguments of the server.

plone-client mcp --profile blog --dry-run

Each tool that changes the site then returns the requests it would send.

Serve over HTTP#

Some assistants connect to a URL instead of starting a command, and a server can then run on another machine. The examples below use a local site; Run a Plone site for testing starts one.

plone-client profile add local --url http://localhost:8080/Plone --username admin --frontend-url http://localhost:3000

Make a token first; the server refuses every request without it. The token is stored in the keyring and printed once, as token. To read it, this example uses jq.

export TOKEN=$(plone-client mcp-token generate | jq -r .token)

Generating a token replaces the one stored before, so run it again only to change the token, then restart the server.

Start the server with --http. It listens on http://127.0.0.1:8000/mcp unless given --host and --port. It normally stays in the foreground of its own terminal; here it runs in the background, so that the next commands can use it.

plone-client mcp --profile local --http > server.log 2>&1 &
export SERVER=$!
sleep 3
cat server.log
plone-client: serving MCP at http://127.0.0.1:8000/mcp

Without the token, the server answers 401.

curl --silent --output /dev/null --write-out '%{http_code}\n' --request POST http://127.0.0.1:8000/mcp
401

With it, the server takes part in the protocol: this is the first message of every client.

curl --silent --request POST http://127.0.0.1:8000/mcp --header "Authorization: Bearer $TOKEN" --header "Content-Type: application/json" --header "Accept: application/json, text/event-stream" --data '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "curl", "version": "1"}}}' | sed -n 's/^data: //p' | jq -c '.result | {protocolVersion, serverInfo: .serverInfo.name}'
{"protocolVersion":"2025-06-18","serverInfo":"plone-client"}

Then register the URL with your client, sending the token in the Authorization header. Keep the token out of files that you commit: each client below has its own way.

claude mcp add --transport http plone-blog http://127.0.0.1:8000/mcp --header "Authorization: Bearer $TOKEN"

Cursor reads the token from an environment variable.

{
  "mcpServers": {
    "plone-blog": {
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "Authorization": "Bearer ${env:PLONE_MCP_TOKEN}"
      }
    }
  }
}

VS Code asks for the token once, and stores it.

{
  "inputs": [
    {
      "type": "promptString",
      "id": "plone-token",
      "description": "Token of the Plone MCP server",
      "password": true
    }
  ],
  "servers": {
    "plone-blog": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "Authorization": "Bearer ${input:plone-token}"
      }
    }
  }
}

bearer_token_env_var names the environment variable that holds the token.

[mcp_servers.plone-blog]
url = "http://127.0.0.1:8000/mcp"
bearer_token_env_var = "PLONE_MCP_TOKEN"
gemini mcp add --transport http --header "Authorization: Bearer $TOKEN" plone-blog http://127.0.0.1:8000/mcp

Connect from Python#

The mcp package has a client, for a program of your own.

import asyncio
import os

import httpx2
from mcp import Client
from mcp.client.streamable_http import streamable_http_client

URL = "http://127.0.0.1:8000/mcp"


async def main() -> None:
    headers = {"Authorization": f"Bearer {os.environ['TOKEN']}"}
    async with httpx2.AsyncClient(headers=headers) as http:
        async with Client(streamable_http_client(URL, http_client=http)) as client:
            tools = await client.list_tools()
            print(len(tools.tools) > 0)
            result = await client.call_tool("site_info", {})
            print(result.content[0].text)


asyncio.run(main())
python client.py
True
{
  "url": "http://localhost:8080/Plone",
  "authenticated": true,
  "username": "admin",
  "credentials_rejected": false,
  "read_only": false,
  "plone_version": "6.1.5",
  "frontend_url": "http://localhost:3000",
  "dry_run": false
}

To start a server on your computer instead, pass StdioServerParameters(command="plone-client", args=["mcp", "--profile", "blog"]) from the mcp package to Client.

Stop the server when you are done.

kill "$SERVER"

To reach the server from another machine, listen on another address with --host, and put a proxy that adds TLS in front of it.

Run the server in a container#

The Compose file has an mcp service that serves the sample site over HTTP. It takes the token from PLONE_CLIENT_MCP_TOKEN, and it starts only when you ask for its profile.

export PLONE_CLIENT_MCP_TOKEN=$(openssl rand -hex 32)
docker compose --profile mcp up --wait

The server listens on http://127.0.0.1:8000/mcp, a few seconds after the command returns, because the container installs plone-client when it starts. Set MCP_PORT to use another port. Outside this sample, set the token the same way in any container, where there is no keyring.