# Connect Cursor to xpnAI

Use this guide for Cursor desktop, Cursor Agents, and Grok Bot when its available connector tools confirm that it uses Cursor's MCP configuration. Follow [the connection guide](https://help.xpnai.app/connect.md) for Workspace access and final verification. The canonical URL of this guide is https://help.xpnai.app/clients/cursor.md.

## Configure the connection

Inspect existing connections and reuse one authorized for the intended Workspace. Use the host's available connector tools or its documented MCP settings to add `https://api.xpnai.app/mcp` as a remote Streamable HTTP server named `xpnAI`. Preserve unrelated connections. Use a Workspace-specific name for an additional Workspace.

Check the installed client's help or [Cursor's MCP documentation](https://cursor.com/docs/mcp) for supported configuration and authentication actions. Tool names and status labels vary by interface; use only tools actually available in this session. A request to connect xpnAI authorizes the applicable setup steps, subject to the host's approval requirements.

- If authentication is required, start the host's supported authenticate action and wait for the user to finish sign-in and approve the intended Workspace. Use its connect card or browser flow as provided. Do not construct an authorization URL yourself.
- If connected, discover tools and call `get_context` as described in the connection guide.
- If the host reports `unreachable`, `failed_to_load`, or a missing sign-in card, inspect the available connection error before choosing a recovery step. These messages alone do not prove that registration failed.

## Missing sign-in or tools

Keep the user on MCP setup when the sign-in prompt is missing or blank. Do not restart Workspace, trial, or Xero setup. Use the client's supported authentication settings if the in-chat prompt is unavailable. If no supported authentication action is accessible, explain that limitation and give the relevant remaining step.

For a temporary connection or tool-loading failure, retry the supported reload or reconnect action once. Preserve the existing configuration. Remove and re-add an entry only when the client's documented recovery requires it, after retaining its settings. Do not repeat the same registration request after a deterministic rejection.

If registration reports `invalid_redirect_uri`, use the static configuration below when the host supports a supplied client ID. If authentication succeeded but tools are absent, check that the connection and tools are enabled in this conversation and reload discovery. Report verification as incomplete; missing tools alone do not prove OAuth failed.

## Static OAuth after a registration failure

Cursor supports a supplied client ID in its remote server configuration. Use this fallback only when the intended host supports static OAuth configuration and uses a callback registered for that client. Static configuration does not bypass user consent or fix a network outage.

Cursor documents these callbacks:

- Web and Cursor Agents: `https://www.cursor.com/agents/mcp/oauth/callback`
- Desktop: `http://localhost:8787/callback`

xpnAI accepts both. Its registration endpoint rejects `cursor://anysphere.cursor-mcp/oauth/callback`; one rejected URI rejects the entire registration. Do not add speculative callbacks or substitute a callback the host does not actually use.

Reuse an existing suitable client ID for this authorization server when available. Otherwise, when the host supports these callbacks, register a public client with the following request. Include only the callbacks needed for the intended interfaces; this example supports both:

```http
POST https://api.xpnai.app/api/mcp/oauth/register
Content-Type: application/json

{
  "client_name": "Cursor",
  "redirect_uris": [
    "https://www.cursor.com/agents/mcp/oauth/callback",
    "http://localhost:8787/callback"
  ],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}
```

Require a successful registration response and use its returned `client_id`. Check that its returned callbacks include the host's actual callback. Keep the ID associated with this xpnAI authorization server. It is a public identifier, not a user credential; no client secret is issued.

For a Cursor interface that uses `mcp.json`, merge this entry into its existing configuration, replacing the placeholder with the returned ID:

```json
{
  "mcpServers": {
    "xpnAI": {
      "url": "https://api.xpnai.app/mcp",
      "auth": {
        "CLIENT_ID": "<returned client_id>",
        "scopes": ["openid", "offline_access", "xpnai:finance"]
      }
    }
  }
}
```

For a hosted agent, use its documented equivalent only if it supports these fields. A local `mcp.json` edit does not configure a remote host. If static configuration is unavailable, report the registration failure and the host limitation rather than claiming the fallback succeeded.

Start the client's normal OAuth flow again. The client must use S256 PKCE and send `resource=https://api.xpnai.app/mcp` in authorization and token requests. Leave that protocol work to its OAuth implementation. The user signs in, chooses the Workspace, and approves access. Onboarding needs the finance-read scope; request journal or chart write scopes only when the user's intended work requires them. Never copy tokens or browser cookies into chat.

## Verify access

Discover the server's tools and call `get_context`. Report the intended Workspace and each returned organisation's name, `isSelected`, `importState`, and `lastSyncedAt`. A pending import does not prevent MCP connection verification, but it limits finance work. An empty organisation list does not establish zero balances. Return to the connection guide for the tool introduction without running demonstration queries.

For human-readable setup and troubleshooting, use [Connect an MCP client](https://help.xpnai.app/guides/connect-an-mcp-client/#cursor-and-grok-bot).