Understand read and write scopes
An explicitly enabled main-site network connection also supports network:sites:read and network:sites:write. The corresponding MCP/content scopes, current Unlimited entitlement, network write policy and super-administrator authorization remain required. Existing grants do not gain these scopes automatically. See Manage multisite pages.
Scopes say what an OAuth token is allowed to attempt. They are the first of the four checks every call passes.
The eight scopes
| Scope | Covers |
|---|---|
mcp:read |
Listing and reading through the protocol |
mcp:write |
Any state-changing operation |
wp:content:read |
Reading posts, pages, media, taxonomies, comments, meta, options, menus |
wp:content:write |
Changing them |
pom_theme:read |
Reading POM Theme settings, content models and templates |
pom_theme:write |
Changing them |
woocommerce:catalog:read |
Reading products, variations, attributes and coupons |
woocommerce:catalog:write |
Changing them |
They come in read and write pairs across four areas. The mcp: pair is transversal; the other three follow the product boundaries.
Account connections
The account gateway advertises mcp:read, mcp:write, account:sites:read and account:sites:execute. Discovery/reading requires the two read scopes; execution requires mcp:read, mcp:write and account:sites:execute. Include account:sites:read for the surrounding inspection workflow. Each destination must also have a separate site grant. Current licensing, that grant, the WordPress actor and local write gates remain authoritative. Account consent covers current and subsequently enrolled websites.
Tools require several at once
A tool declares every scope it needs, and the token must carry all of them.
Write operations declare mcp:write and their area’s write scope. For example, wc_update_product requires mcp:write and woocommerce:catalog:write; reading that product requires mcp:read and woocommerce:catalog:read. POM Cache clearing declares mcp:write without an area scope.
WordPress MCP Adapter additionally requires mcp:read to access the transport. Include the area’s read scope when the workflow must inspect current state before writing or verify the result afterwards; it is not implicitly granted by the write scope.
How scopes are granted
At registration, a client may request scopes. If it asks for none, it is registered with all eight available to request later.
At authorization, the client asks for a subset, and you see them on the consent screen. Omitting the parameter falls back to the client's registered scopes.
Unknown scope strings are discarded rather than causing an error, so a client asking for something that does not exist simply does not get it.
API keys use a service user
These per-client scope grants apply to OAuth. API key calls use the configured service user’s capabilities and can write when the required gates are open. They do not provide separate scopes for each client sharing the key. See Use an API key.
Scopes are not permission
A token with every scope still cannot do something the acting WordPress user cannot do, and still cannot write while the relevant write gate is closed.
Think of scopes as what the client is allowed to ask for, capabilities as what the user is allowed to do, and gates as what the site owner has switched on. See MCP security model.
Choosing what to approve
Approve the narrowest set that lets the work happen.
| Task | Reasonable scopes |
|---|---|
| Answering questions about the site | mcp:read, wp:content:read |
| Editing posts and pages | Add mcp:write, wp:content:write |
| Catalogue maintenance | Add the woocommerce:catalog:* pair |
| Templates and theme settings | Add the pom_theme:* pair |
| Read-only reporting across everything | All four read scopes, no write scopes |
A read-only token is a legitimate permanent configuration and the right default for an assistant you are still evaluating.
Widening later
Scopes are fixed for the life of a token. To widen them the client repeats the authorization flow and you approve the larger set; refreshing keeps the original scopes.
That is a feature: start narrow, widen deliberately when a task needs it.
Reducing what a token can reach
Three ways, in increasing severity:
- Close the write gate for that area. Immediate, reversible, and it affects every client.
- Reduce the acting user's capabilities.
- Reset OAuth, revoking every client and token for the site.
The first is usually the right response to "this assistant is doing more than I expected".
Diagnosing a scope error
pom_ai_mcp_scope_denied means the token lacks a scope the tool requires. Check, in order:
- Which scopes were actually approved — the MCP log records the authorization.
- Whether native transport access needs
mcp:read, or a separate read operation needs the area’s read scope. - Whether the client requested a narrower set than you assumed.
If the token has the scopes, the refusal is coming from a different check: a capability error names the WordPress capability, and a closed gate says the write group is disabled in the settings.