Hosting & Troubleshooting
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.
claude mcp remove kirby, then add the MCP URL again.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:
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]
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;
}
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:
SetEnvIf Authorization "(.+)" HTTP_AUTHORIZATION=$1
On nginx with PHP-FPM, pass the header in the block that hands requests to PHP:
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:
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:
| The agent says | What to do |
|---|---|
| … contains …, which the site doesn't accept from agents | Ask for the value without it, or add that markup in the Panel |
| … unsaved changes, which someone may still be working on | Publish or discard the changes before the agent deletes the page or file |
| … is editing this content in the Panel | Wait until your colleague leaves the page's view, or ask them to publish or discard their changes |
| The draft has unsaved changes …, so it stays a draft | Let the agent publish the changes first, or publish them in the Panel |
| The changes have validation errors | Let the agent fix the named fields, or fix them in the Panel, before publishing |
| The page has validation errors, so it stays a draft | Let the agent fix the named fields and publish the fix, or fix them in the Panel, before it changes the status |
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.