Getting started

Upgrading

Move to the latest release, which fixes security issues, and what the versioning policy promises.

On this page

The changelog lists every change. This page covers what you have to act on.

From 1.0 to 1.1#

1.1.0 adds no config keys or migrations, and it fixes security issues, so upgrade.

composer require danielgnh/statamic-mcp:^1.1

If the site caches routes and your deploy doesn’t rebuild that cache, run this after updating. A route cache built before the update points the Connections page at a controller method that moved, so that page answers 500. It also keeps the MCP route’s old middleware order, so GET and DELETE skip the kill switch and the throttle.

php artisan route:cache

What can stop working#

  • URL uploads need ext-curl, with curl_exec enabled. A server without it now refuses them. Guzzle’s stream handler ignored the address pin, which is why it’s no longer used.
  • A proxy can refuse downloads. Through an HTTP proxy, a download now sends CONNECT to the validated IP instead of the hostname, so a proxy that filters CONNECT by hostname or port may refuse it.
  • More addresses are refused. A site that downloads from a documentation, benchmarking, multicast, or other special-purpose range on its own network now gets a refusal, and uploads.source_allowlist doesn’t override it.
  • A fieldtype that throws a plain Exception on a bad value now gives the agent the generic error. Throw InvalidArgumentException to keep a message that names the field.
  • One user can hold at most 100 tokens through the Control Panel. mcp:token on the console has no limit.

The changelog has the full list, with the security fixes described.

From 0.9 to 1.0#

1.0.0 adds no config keys or migrations. Two things change around it: the addon needs laravel/mcp 1.1.2 or newer, and augmented reads return related entries and users in a shorter form. A site that published the OAuth consent view has one more step.

Update the packages#

Your composer.json pins a 0.x release, so require the new major and let Composer move laravel/mcp along with it.

composer require danielgnh/statamic-mcp:^1.0 --with-all-dependencies

If Composer stops with a conflict, something else holds laravel/mcp at 0.x. composer why laravel/mcp names it.

Your own composer.json, if you installed laravel/mcp yourself, as Laravel’s MCP docs do. Composer says the release conflicts with your root composer.json require. Require both at once.

composer require danielgnh/statamic-mcp:^1.0 laravel/mcp:^1.1.2 --with-all-dependencies

laravel/boost older than 2.9.0, the first Boost that allows laravel/mcp 1.x. Composer says laravel/mcp[v1.1.2] was not loaded because it conflicts with another require. Update Boost in the same step.

composer require danielgnh/statamic-mcp:^1.0 --no-update
composer update danielgnh/statamic-mcp laravel/boost --with-all-dependencies

Another package. Once it has a release that allows laravel/mcp 1.x, update it the same way as Boost.

If the app serves MCP servers of its own next to this addon, they move to laravel/mcp 1.x too. Its 1.0.0 release notes list what changed.

Rebuild a cached route list#

The MCP route and the OAuth discovery and client registration routes now check enabled and auth on every request, and client registration is throttled. Passport’s own routes, such as /oauth/authorize and /oauth/token, don’t check either setting. A route cache built before the update keeps serving the old routes. If the site caches routes and your deploy doesn’t rebuild that cache, run this after updating.

php artisan route:cache

The consent page now shows where approving sends the editor, so a client registered as “Claude” with someone else’s redirect URI can’t pass for Claude. If you published the view, your copy in resources/views/vendor/statamic-mcp/oauth/authorize.blade.php doesn’t show it. Publish it again with --force and reapply your changes.

php artisan vendor:publish --tag=statamic-mcp-views --force

To patch your copy by hand instead, take every part from the addon’s view, or the page fails or overflows on phones: the $redirect… lines at the end of the @php block at the top, the .ui-redirect styles, min-width: 0 on main, and the @if ($redirect) block above the buttons.

What agents and integrations see#

  • With format: augmented, entries_get and terms_get return a related entry that Statamic adds itself, such as parent, in Statamic’s short form (id, title, url, permalink, api_url). Every user, updated_by included, is {id, name, api_url}, with email only for a caller who has view users. Augmented terms_get no longer has entries or entries_count. Raw reads, the default, are unchanged.
  • When resources limits what MCP exposes, agents no longer get the title, URL, or status of the rest in navigation menus, augmented reads, or blueprint field options. Stored values stay. A raw read returns the id of a related entry, the slug of a term, or the path of an asset outside the exposure as stored, and navigations_get returns a linked entry’s id and any title set on the branch itself. Opening that id answers not found. navigations_update refuses a new link to an entry outside the exposure, and writes refuse a new file from a hidden container. entries, terms, and link fields don’t check the exposure, so entries_create and entries_update can store a value outside it.
  • Coming from laravel/mcp 0.x, a JSON-RPC error no longer comes back with HTTP 200. An unknown method gets 404, an internal error 500, and any other error, an unknown tool included, 400, each with the JSON-RPC error in the body. MCP clients handle this. Check scripts that call the endpoint and expect 200.
  • In OAuth mode, only tokens issued for Statamic users sign in. A token from a Passport client of another user provider, or a client credentials token, no longer does. Client registration allows 60 requests a minute per address, a budget it shares with /oauth/token and the MCP route’s default throttle.

From an older 0.x release#

Follow the steps above, then go through the changelog entries marked Breaking for each release you skip. From 0.6 or older, move the guidelines for agents, as Guidelines for agents describes.

php please mcp:guidelines

Then run the doctor. It names any step still missing, such as php artisan migrate for an OAuth setup from before the key table.

php please mcp:doctor

What the version number promises#

Releases follow semantic versioning. A minor or patch release keeps these working:

  • tool names, their parameters, and their response fields
  • config keys and environment variables
  • Artisan and please commands
  • the HTTP routes
  • the extension API in Adding your own tools: Server, ToolRegistry, the Tool base class with its listed helpers, ToolException, and the built-in tool classes, which you can replace, remove, or subclass by name

Other classes under src/, the traits in Tools/Concerns included, are internal.

Start here