---
title: "Connect an Agent"
description: "Turn on agents, add the MCP URL to Claude Code, Cursor, or another agent, approve its permissions in the Panel, and manage its connection."
canonical_url: "https://kirby.tools/docs/copilot/agents"
---

# Connect an Agent

> Turn on agents, add the MCP URL to Claude Code, Cursor, or another agent, approve its permissions in the Panel, and manage its connection.

An agent is an AI application outside the Panel that reads the site's content and prepares changes to it – Claude Code, claude.ai, 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.

## Step 1: Turn On Agents

Set the `agents` option:

```php [site/config/config.php]
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`:

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

<callout color="info" icon="i-ri-server-line" to="/docs/copilot/agents/hosting">

If the Agents view reports a problem with your server, **Hosting & Troubleshooting** has the fix.

</callout>

## Step 2: Add the MCP URL to Your Agent

### Claude Code

Add the MCP URL as an HTTP server:

```bash
claude mcp add --transport http kirby https://example.com/api/copilot/mcp
```

Then run `/mcp` in Claude Code, or `claude mcp login kirby` in the terminal, to connect. Your browser opens the Panel's login.

### Cursor

Add the MCP URL to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` for all projects:

```json [.cursor/mcp.json]
{
  "mcpServers": {
    "kirby": {
      "url": "https://example.com/api/copilot/mcp"
    }
  }
}
```

Cursor then takes you through the same Panel login.

### Other Agents

Any agent that supports remote MCP servers over HTTP with OAuth connects the same way: add the MCP URL where the agent takes remote MCP servers, and it sends you to the Panel's login. Where that setting sits, and which plans include it, differs per agent – claude.ai and Claude Desktop take the URL as a [custom connector](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp), ChatGPT as an app in [developer mode](https://developers.openai.com/api/docs/guides/developer-mode).

claude.ai, Claude Desktop, and ChatGPT reach the MCP URL from their own servers, so they need 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:

<panel-mock>
<panel-copilot-agents-authorize-view :client="{"name":"Claude","host":"claude.ai"}" :redirect="{"label":"claude.ai"}" account="editor@kunsthalle-leipzig.de" site="Kunsthalle Leipzig">



</panel-copilot-agents-authorize-view>
</panel-mock>

It lists four permissions:

<table>
<thead>
  <tr>
    <th>
      Permission
    </th>
    
    <th>
      Preselected
    </th>
    
    <th>
      Lets the agent
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Read content
    </td>
    
    <td>
      Always
    </td>
    
    <td>
      Read the pages, files, and fields your role can access
    </td>
  </tr>
  
  <tr>
    <td>
      Prepare changes
    </td>
    
    <td>
      Yes
    </td>
    
    <td>
      Write unsaved changes and create drafts
    </td>
  </tr>
  
  <tr>
    <td>
      Publish changes
    </td>
    
    <td>
      No
    </td>
    
    <td>
      Publish or discard changes, change a page's status, slug, or parent, and upload files
    </td>
  </tr>
  
  <tr>
    <td>
      Delete content
    </td>
    
    <td>
      No
    </td>
    
    <td>
      Delete pages and files
    </td>
  </tr>
</tbody>
</table>

A permission is disabled when your role has none of the Kirby permissions behind it – **Delete content**, for example, without `pages.delete` and `files.delete`. Click **Connect**, and the browser returns to the agent.

<callout color="info" icon="i-ri-shield-check-line" to="/docs/copilot/agents/permissions-and-review">

What each permission allows, and how an agent's changes reach the published site: **Permissions & Review**.

</callout>

## 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:

```yaml [site/blueprints/users/client.yml]
title: Client
permissions:
  access:
    copilot-agents: false
```

Agents that the role's users already connected stop working too.

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

```yaml [site/blueprints/users/editor.yml]
title: Editor
permissions:
  johannschopplich.copilot:
    agentsPublish: false
    agentsDelete: false
```

Connections that already have the permission lose it on their next request.

## Manage Connections

The Agents view lists your connections: the agent, the permissions you gave it, and when it was last active. Next to the agent's name is the domain it identified with, or **Unverified** when the agent chose its name itself, plus **local app** when it runs on your computer. Admins see every user's connections, with the account each one works as, and can revoke any of them.

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

A connection also ends when:

- the agent goes unused for 30 days
- you change your password
- your account is deleted

To connect the agent again, start its login again – in Claude Code through `/mcp` – and approve the connection in the Panel.

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. Agents keep the tools they loaded when they connected. In ChatGPT, refresh the app in its settings and start a new chat. In claude.ai, disconnect the connector and connect it again, which asks for the permissions anew.

---

Every page of this site as Markdown: <https://kirby.tools/sitemap.md>