---
title: "Hosting & Troubleshooting"
description: "Fix the server problems the Agents view reports, from a subfolder install to a missing Authorization header, and read why an agent's write is refused or rate-limited."
canonical_url: "https://kirby.tools/docs/copilot/agents/hosting"
---

# Hosting & Troubleshooting

> Fix the server problems the Agents view reports, from a subfolder install to a missing Authorization header, and read why an agent's write is refused or rate-limited.

## The Agents View Checks Your Server

Each time you open the Agents view, it checks the URLs an agent loads before it connects, and names the problems it finds, with the fix.

<note>

Claude Code remembers the login server of an earlier connection. After you change a server rule, run `claude mcp remove kirby`, then add the MCP URL again.

</note>

### Agents Can't Load the Discovery Documents

Agents find the Panel's login through two documents at the root of your domain:

- `/.well-known/oauth-protected-resource`
- `/.well-known/oauth-authorization-server`

Many hosts answer requests to `/.well-known/` themselves, so they never reach Kirby. Pass both paths, and the paths below them, to Kirby's `index.php`.

### Kirby Runs in a Subfolder

With Kirby in a subfolder, requests to the domain root never reach it. Add two rules at the domain root that pass the discovery documents to Kirby. For a Kirby in `/cms`:

<code-group>

```apache [.htaccess]
RewriteEngine on
RewriteRule ^\.well-known/oauth-protected-resource$ /cms/.well-known/oauth-protected-resource [L]
RewriteRule ^\.well-known/oauth-authorization-server/cms$ /cms/.well-known/oauth-authorization-server [L]
```

```nginx [nginx]
location = /.well-known/oauth-protected-resource {
    rewrite ^ /cms/.well-known/oauth-protected-resource last;
}
location = /.well-known/oauth-authorization-server/cms {
    rewrite ^ /cms/.well-known/oauth-authorization-server last;
}
```

</code-group>

Replace every `cms` with your subfolder, including the end of the second rule's source path. On nginx, the rules sit next to Kirby's usual `location /cms/` block.

### Agents Can't Log In

Your server drops the `Authorization` header before the request reaches Kirby. On Apache, add the line from Kirby's own `.htaccess`:

```apache [.htaccess]
SetEnvIf Authorization "(.+)" HTTP_AUTHORIZATION=$1
```

On nginx with PHP-FPM, pass the header in the block that hands requests to PHP:

```nginx
fastcgi_param HTTP_AUTHORIZATION $http_authorization;
```

### The MCP URL Starts With `http://`

Agents connect only over HTTPS. Behind a proxy that doesn't forward the scheme, Kirby builds its URLs with `http://` while the Panel runs on `https://`. Set Kirby's `url` option to your `https://` address:

```php [site/config/config.php]
return [
    'url' => 'https://example.com'
];
```

### Agents Can't Reach the MCP URL

A firewall, a security plugin, or a server rule may block POST requests to the MCP URL. Allow them for that URL.

## Why an Agent's Write Is Refused

A refused write tells the agent why:

<table>
<thead>
  <tr>
    <th>
      The agent says
    </th>
    
    <th>
      What to do
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      … contains …, which the site doesn't accept from agents
    </td>
    
    <td>
      Ask for the value without it, or add that markup in the Panel
    </td>
  </tr>
  
  <tr>
    <td>
      … unsaved changes, which someone may still be working on
    </td>
    
    <td>
      Publish or discard the changes before the agent deletes the page or file
    </td>
  </tr>
  
  <tr>
    <td>
      … is editing this content in the Panel
    </td>
    
    <td>
      Wait until your colleague leaves the page's view, or ask them to publish or discard their changes
    </td>
  </tr>
  
  <tr>
    <td>
      The draft has unsaved changes …, so it stays a draft
    </td>
    
    <td>
      Let the agent publish the changes first, or publish them in the Panel
    </td>
  </tr>
  
  <tr>
    <td>
      The changes have validation errors
    </td>
    
    <td>
      Let the agent fix the named fields, or fix them in the Panel, before publishing
    </td>
  </tr>
  
  <tr>
    <td>
      The page has validation errors, so it stays a draft
    </td>
    
    <td>
      Let the agent fix the named fields and publish the fix, or fix them in the Panel, before it changes the status
    </td>
  </tr>
</tbody>
</table>

## Requests Fail With 429

A connection may send 120 requests a minute to the MCP URL, and an IP address 30 requests a minute to each step of the login. Beyond that, the site answers with 429 Too Many Requests until the minute is over.

---

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