> ## 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.

# Supported MCP-compatible AI clients for Maxi AI Core

> Maxi AI Core works with any MCP-compatible AI client. This page covers tested clients, recommended connection methods, and known quirks.

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

<CardGroup cols={2}>
  <Card title="ChatGPT (not recommended)" icon="message">
    Connect via OAuth 2.1. Paste the MCP endpoint URL into ChatGPT's connector configuration and authorize in the browser.
  </Card>

  <Card title="Claude Desktop" icon="robot">
    Connect via OAuth 2.1 or application passwords. OAuth is simpler for interactive use; app passwords work for scripted setups.
  </Card>

  <Card title="Cursor" icon="code">
    Connect via OAuth 2.1 or application passwords. OAuth is recommended for day-to-day development work.
  </Card>

  <Card title="Codex" icon="terminal">
    Connect via OAuth 2.1 or application passwords. Read the Codex-specific quirks below before using write abilities.
  </Card>
</CardGroup>

## Connection methods by client

| Client         | OAuth 2.1   | App passwords | Notes                                         |
| -------------- | ----------- | ------------- | --------------------------------------------- |
| ChatGPT        | Recommended | Not supported | Uses OAuth grant identity for session scoping |
| Claude Desktop | Recommended | Supported     | Renders structured errors cleanly             |
| Cursor         | Recommended | Supported     | Renders structured errors cleanly             |
| Codex          | Recommended | Supported     | See write-ability quirk below                 |

For setup instructions, see [Connect with OAuth 2.1](/connect/oauth) or [Connect with application passwords](/connect/app-passwords).

## Session scoping by client

### ChatGPT

<Warning>
  **We currently do not recommend using ChatGPT** for critical Maxi AI Core operations. In our testing, large tool responses may be truncated, which can cause incomplete data to be interpreted incorrectly and lead to unreliable conclusions. For more dependable handling of complex WordPress and WooCommerce tasks, we recommend using **Claude**, **Codex**, **Cursor**, **Manus** or similar agents with Maxi AI Core instead.
</Warning>

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.

<Note>
  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.
</Note>

### 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](/connect/app-passwords#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.

<Tabs>
  <Tab title="Step 1 — check parameter names">
    Verify the parameter names match the ability's `input_schema.properties` exactly. Retry with corrected names.
  </Tab>

  <Tab title="Step 2 — prefetch the rule">
    If parameter names were correct, call `maxi/get-ability-rule` before the ability:

    ```json theme={null}
    {
      "name": "maxi/get-ability-rule",
      "arguments": {
        "ability_id": "maxi/update-content"
      }
    }
    ```

    Then retry your original call. The gate passes it through.
  </Tab>

  <Tab title="Step 3 — check the audit log">
    If both steps above fail, call `maxi/get-audit-events` with `category: "rules"` to see whether your retries reached the server at all.
  </Tab>
</Tabs>

### 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.

```json theme={null}
{
  "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.

<Note>
  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.
</Note>

### 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.