Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.maxicore.ai/llms.txt

Use this file to discover all available pages before exploring further.

When an ability returns "success": false, the error field contains a description of what went wrong. The correct response is always to read that field, understand the cause, and fix the conditions or input before retrying. Retrying blindly — without reading the error — will reproduce the same failure. All server-side errors are also logged to the PHP error log with the prefix [Maxi AI]. If you need to debug a call that isn’t reaching the server or is producing an unexpected response shape, check your PHP error logs first.

​
Common error codes

No valid Maxi AI license is active on this site.What to do: Purchase a license at maxicore.ai, then activate it either through Settings → Maxi AI License in your WordPress admin or by calling maxi/activate-license with your license key.Without an active license, only maxi/bootstrap-session and maxi/activate-license are callable.
Your license is valid, but your current plan does not include the feature group this ability requires.What to do: The error response includes required_group (the group you need) and plan (your current plan). Upgrade to Pro at maxicore.ai. After upgrading, your new plan takes effect on the next license refresh — up to 12 hours, or immediately by navigating to Settings → Maxi AI License and refreshing manually.
The ability has a reject_first rule that has not been acknowledged in this session. The first call to a write or mutation ability always triggers this — it is not a failure of your input.What to do: The rule body is attached to this rejection under _meta._rule. Read the rule content, then retry the exact same call. The retry is treated as the acknowledgement and the ability runs.If your MCP client does not surface the _meta._rule body from the rejection (see the Codex quirk below), call maxi/get-ability-rule with the ability_id first. That call marks the session as acknowledged and your next real call passes through.
No rule exists for this ability — the baseline rule set has not been installed on this site yet.What to do: Call maxi/rules-sync. This installs the baseline rules shipped with the plugin. After rules-sync completes, retry the original ability call.
The content field you sent was empty or whitespace-only. WordPress core’s parse_blocks() rejected it.What to do: Provide a non-empty content value. You can use Gutenberg block HTML, plain HTML, shortcodes, or classic-editor content. See Content format below for valid examples.
You tried to move a note to a status that is not reachable from its current status. Status transitions for notes are PHP-enforced.What to do: Check the error response for the list of valid target statuses from the note’s current state. For example, an agent-note at open can move to acknowledged or archived — not directly to resolved. The archived status is terminal and has no outbound transitions.

​
Capability errors

If you receive a permission error when calling an ability, the authenticated WordPress user does not have the WordPress capability that ability requires. This is enforced at execution time on a per-object basis — it is not enough to have edit_posts generically; you must also have permission on the specific post being edited. To fix this, adjust the WordPress user’s role or capabilities so they match what the ability needs. For a full breakdown of which capability each ability requires and how to scope agent users correctly, see User scoping.

​
Client quirk: generic error messages

Some MCP clients — Codex is the most common example — collapse any "success": false response into the single string "An error occurred while executing the tool." This hides the structured error field and the _meta._rule body that the server sent. The server response is always structured and informative; the client is discarding it. If you see this generic message, the cause is almost always one of two things:
1

Check parameter names

The ability call used a parameter name that does not match the ability’s input_schema. WordPress’s REST validator emits PHP warnings when it encounters unexpected parameters, which can corrupt the response body before the client parses it.Common mistakes: maxi/get-note, maxi/update-note, and maxi/delete-note all use id — not note_id. maxi/get-ability-rule uses ability_id — not ability_name. maxi/get-attachment and maxi/delete-attachment use attachment_id.Retry the call with the exact parameter names from the ability’s input_schema.
2

Prefetch the rule for write abilities

If parameter names were correct and you are calling a write or mutation ability, the reject_first gate triggered a structured rejection that your client is rendering as a generic error.Call maxi/get-ability-rule with the ability’s ID first. This is always callable — it is never itself gated. It marks the session as acknowledged, so your next real call passes through without a rejection.
maxi/get-ability-rule { "ability_id": "maxi/create-content" }
3

Inspect the audit log

If both steps above fail, check whether your retries are reaching the server at all. Call maxi/get-audit-events with category: "rules" to see rule-gate events logged on the server side.
On MCP clients that render structured errors correctly — Claude Desktop, Cursor, and others — you do not need to prefetch rules for read abilities. Only prefetch maxi/get-ability-rule for write abilities (create-*, update-*, delete-*, bulk-*, and similar) when using Codex or a client with the same limitation.

​
Content format

The content field accepted by content abilities must pass through WordPress core’s parse_blocks(). Gutenberg block HTML, plain HTML, shortcodes, and classic-editor content are all valid. The only thing that fails is an empty or whitespace-only string. For new content, use Gutenberg block format: 
<!-- wp:paragraph -->
<p>Your text here.</p>
<!-- /wp:paragraph -->

<!-- wp:heading -->
<h2>Section Title</h2>
<!-- /wp:heading -->

<!-- wp:heading {"level":3} -->
<h3>Sub-heading</h3>
<!-- /wp:heading -->
Plain HTML and shortcodes also work if you are migrating legacy content. Gutenberg block format is preferred for new content because it produces structured, editable blocks in the WordPress editor.

​
Debugging checklist

If an ability is failing and the error message is not clear, work through these steps in order:
  1. Read error in the response — it always describes the cause.
  2. Check your PHP error logs for a line prefixed with [Maxi AI].
  3. Confirm the authenticated user has the required WordPress capability for that ability.
  4. Confirm your site has an active license with the correct plan for the ability’s feature group.
  5. For write abilities on Codex: call maxi/get-ability-rule first, then retry.
  6. For parameter errors: compare the parameter names you sent against the ability’s input_schema.