An agent is an AI application outside the Panel that reads and changes the site's content – Claude, ChatGPT, Cursor, or any other agent that supports remote MCP servers. It works as the Kirby user who connected it, within that user's role, and by default its edits wait in the Panel until an editor publishes them.

The agent brings its own AI model, so the site needs no AI provider for it.

You connect an agent through the Panel's own login, two-factor codes included, so nobody creates or shares an API token.

Step 1: Turn On Agents

Set the agents option:

return [
    'johannschopplich.copilot' => [
        'agents' => true
    ]
];

The Panel menu then has an Agents entry. Its view shows the MCP URL, which you add to your agent, and checks whether agents can reach it. By default, the MCP URL is your site's URL followed by /api/copilot/mcp:

https://example.com/api/copilot/mcp

Step 2: Add the MCP URL to Your Agent

Add the MCP URL where your agent takes remote MCP servers – in Claude as a custom connector, in ChatGPT as a custom MCP server. The agent then sends you to the Panel's login.

Connected this way, an agent reaches the MCP URL from its provider's servers, so it needs a site that's reachable from the internet.

Step 3: Approve the Connection

After you log in to the Panel, the consent view names the agent, the site, and the account the agent will work as:

It lists four permissions:

Publish changes and Delete content stay unticked until you tick them, even when the agent asks for them. When an agent that's still connected comes back, for example to ask for a permission it lacks, the consent view starts from what its most recently active connection holds instead – unless the agent is unverified. A permission your role doesn't allow is disabled. Click Connect, and the browser returns to the agent.

Limit Agents by Role

Every user who can access the Panel can connect agents. To keep a role out, take away its access to the Agents view in the role's blueprint:

title: Client
permissions:
  access:
    copilot-agents: false

Connections that the role's users already made stop working while the role is kept out.

A role can also withhold Publish changes or Delete content from agents while its users still publish and delete in the Panel:

title: Editor
permissions:
  johannschopplich.copilot:
    agentsPublish: false
    agentsDelete: false

Connections that already have the permission can't use it while the role withholds it. Once the role allows it again, an agent sees the permission's tools after it reloads its tool list, which some chat apps do only when you reconnect the agent.

Manage Connections

The Agents view lists your connections: the agent, the permissions you gave it, and when it was last active. An agent marked Unverified chose its name itself. Admins see every user's connections, with the account each one works as, and can revoke any of them. A connection marked Role has no access belongs to a user whose role may no longer connect agents; it works again if the role may.

Revoke in a connection's menu ends it at once.

A connection also ends when:

• the connection goes unused for 30 days
• your password changes, or you set up or disable one-time codes for your login
• your account is deleted

To connect an agent again, start its login and approve the connection in the Panel. Connecting an agent that's still connected adds a second connection, and the old one stays in the Agents view until it ends or you revoke it.

When the site's URL changes, for example from http:// to https://, agents have to connect again – revoke their old connections in the Agents view.

To give a connection other permissions, choose Change permissions in its menu. Only the user who connected it can, within what their role allows. The agent works with the new permissions from its next call on. A permission your role withholds for now stays with the connection and applies again once your role allows it.

When an agent needs a permission its connection lacks and your role allows, it can send you through the consent view again to ask for it.