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.

Maxi AI Core works with any client that supports the Model Context Protocol (MCP). Because the plugin exposes a standard MCP endpoint, any MCP-compatible client can connect — the clients below are specifically tested and documented.

​
Client overview

ChatGPT

Connect via OAuth 2.1. Paste the MCP endpoint URL into ChatGPT’s connector configuration and authorize in the browser.

Claude Desktop

Connect via OAuth 2.1 or application passwords. OAuth is simpler for interactive use; app passwords work for scripted setups.

Cursor

Connect via OAuth 2.1 or application passwords. OAuth is recommended for day-to-day development work.

Codex

Connect via OAuth 2.1 or application passwords. Read the Codex-specific quirks below before using write abilities.

​
Connection methods by client

ClientOAuth 2.1App passwordsNotes
ChatGPTRecommendedNot supportedUses OAuth grant identity for session scoping
Claude DesktopRecommendedSupportedRenders structured errors cleanly
CursorRecommendedSupportedRenders structured errors cleanly
CodexRecommendedSupportedSee write-ability quirk below
For setup instructions, see Connect with OAuth 2.1 or Connect with application passwords.

​
Session scoping by client

​
ChatGPT

ChatGPT’s browser MCP connector opens a new MCP transport session for each tool call rather than maintaining a persistent session. Maxi AI Core handles this automatically — when you connect via OAuth, your session state (rule acknowledgements, playbook acknowledgements) is scoped to your OAuth authorization, not the individual MCP transport session. This means you bootstrap once per authorization, not once per tool call.
Because ChatGPT scopes session state to the OAuth grant, you must complete the OAuth authorization flow at least once. After that, the session carries forward automatically across tool calls.

​
Claude Desktop and Cursor

These clients maintain stable Mcp-Session-Id values across tool calls within a session. Session state is scoped to the Mcp-Session-Id header, which works naturally with the standard rule acknowledgement and playbook acknowledgement flows.

​
Application password clients

Clients using application passwords without OAuth should send a consistent Mcp-Session-Id header throughout each logical working unit. See Session identity with Mcp-Session-Id for details.

​
Client quirks

​
”An error occurred while executing the tool”

Some clients — most commonly Codex — collapse any success: false response into the generic string "An error occurred while executing the tool.", hiding the structured error details that explain what went wrong. If you see this message, it usually means one of two things:
  1. Wrong parameter name. The ability received a parameter name that doesn’t match its input schema. Common examples: 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. Check the parameter names and retry.
  2. Rule gate triggered. The ability uses reject_first delivery — the first call is intentionally rejected so the agent can read the rule before proceeding. On clients that hide structured errors, this rejection looks like a generic error. Call maxi/get-ability-rule with the ability’s ID first, then retry the original call.
Verify the parameter names match the ability’s input_schema.properties exactly. Retry with corrected names.

​
Codex: prefetch write abilities before first call

Codex does not reliably send a retry after a reject_first rule rejection. The workaround is to call maxi/get-ability-rule before the first call to any write ability — this pre-marks the session as acknowledged so the real call passes through immediately. Which abilities need prefetch in Codex: any ability that creates, updates, deletes, or mutates data. This includes create-*, update-*, delete-*, assign-*, set-*, bulk-*, generate-*, upload-*, manage-*, and run-wp-cli. Which abilities do not need prefetch: all read abilities (get-*, list-*, search-*) use inline_on_success delivery — they execute on the first call and attach the rule to the successful response. No prefetch, no reject. 
{
  "name": "maxi/get-ability-rule",
  "arguments": {
    "ability_id": "maxi/create-content"
  }
}
Call this once per write ability per session, then proceed with the actual call.
Claude Desktop, Cursor, and other clients that render structured errors do not need prefetch. On a reject_first rejection, these clients can read the rule from the rejection response and retry normally.

​
Parameter names apply to all clients

Even on clients that display structured errors, sending a wrong parameter name causes PHP validation warnings that can corrupt the JSON response. Always use the exact parameter names from the ability’s input_schema. When in doubt, call maxi/get-ability-rule — the rule body includes the correct parameter names.