Connect an MCP client

An MCP client is an assistant that can connect to xpnAI and use its finance tools. You add the xpnAI server URL to your assistant, sign in to xpnAI and choose the Workspace it can access.

Any Workspace member can connect their own assistant. You need an active MCP subscription or trial. Your assistant account must also allow custom MCP connections; your employer may need to enable them in the assistant product.

To sign out of xpnAI in your browser, choose Sign out from your user menu or open /logout on your xpnAI site. Both return you to /login to sign in again.

To close the user menu, click anywhere outside it, including the navigation sidebar, or press Escape.

Download Xero attachments

Ask your assistant to download attachments for bills, sales invoices or manual journals in a selected Xero organisation. For example:

Download all bill attachments dated 1 July to 30 September 2026, and give me a ZIP with an index.

The date range includes both dates and uses the document date, not the date a file was attached. Only documents marked as having attachments in the latest synchronised Xero records are selected. Synchronise Xero first if documents or their attachments recently changed.

Your assistant first starts discovery. xpnAI reports how many documents match and how many it has checked. Each document can have several files, so file counts remain provisional until discovery finishes. Documents that could not be checked are reported separately.

After discovery, ask the assistant to download the files. xpnAI shows files already stored, files downloaded, files still required and failures. Work continues if you close the conversation. Xero’s limits can pause a job; it resumes automatically when the allowance becomes available. Ask your assistant to check the job’s progress or cancel remaining work.

For one document, you receive separate file links. For a batch, you receive a ZIP. Extract it and open index.html to browse files under their organisation and document type, ordered by document date. Organisation names, document references and recorded contacts link to Xero. The xpnAI logo links to xpnAI. The index works offline; links to Xero and xpnAI require internet access. Documents marked as having attachments remain listed if no files were retrieved, with an explanation. The index and manifest.json also identify missing files and errors. A partial export does not mean every requested file was retrieved.

Each request supports up to 5,000 documents, 32 MB per file and 2 GB of attachments per batch. Narrow the date range for larger selections. Oversized files are reported as failures. General ledger journal entries are not supported as attachment owners; ask for their source bill, invoice or manual journal.

Previously downloaded files are reused. If a file may have been replaced in Xero, ask for a refresh with a new discovery request. Matching filenames and sizes do not prove that a stored copy is still current.

Download links last 15 minutes. Ask for the job again to get new links. ZIPs are kept for one day; ask the assistant to prepare the download again if the ZIP has expired. Stored attachment copies remain available while the Workspace retains its data. Retrieving them requires the organisation to remain connected and selected. Anyone with a download link can use it until it expires, so share it only with intended recipients.

If Xero refuses access, reconnect with attachment permissions and retry the job. Retrying downloads does not change bills, invoices or journals in Xero.

MCP server address

Use this address in your assistant’s connection settings:

https://api.xpnai.app/mcp

All Workspaces use the same server URL. You choose the Workspace when you sign in to authorise the assistant. Do not use the address of the xpnAI page in your browser as the server URL. In xpnAI, Connections > MCP shows the same address with a copy button beside it.

Install an available connector

If xpnAI is available in your assistant’s directory or your organisation’s approved connector list, select it and choose Connect or Install. Follow the xpnAI sign-in screen using your usual social sign-in provider, choose your Workspace and approve the requested permissions. Enable the connection in your conversation, then ask the assistant which Workspace and organisations it can access.

Installing a connector does not create an xpnAI Workspace or start a subscription. You still need membership and an active MCP subscription or trial. Your assistant’s organisation administrator may need to enable the connector before you can use it.

If no xpnAI listing is available, use the setup request or manual connection instructions below. You do not need to add a second connection when an existing one already accesses the intended Workspace.

Ask your agent to set it up

Many agents can configure an MCP connection for you. Try sending this request to your agent:

I already have the xpnAI Workspace "<Workspace name>". Read https://help.xpnai.app/connect.md to connect this assistant to that Workspace. Verify the Workspace after connecting.

Replace <Workspace name> with your Workspace name, or open Connections > MCP and copy the Agent prompt above the MCP server URL. That prompt already includes your current Workspace name.

Your agent connects the assistant you are using to your existing Workspace and verifies the connection. It does not repeat Workspace creation or Xero setup. If you are starting from scratch, use Getting started instead.

The agent performs the setup steps it can access and gives you instructions specific to your assistant for anything you need to do yourself.

Follow any prompts to sign in to xpnAI, choose your Workspace and approve the requested permissions. You still complete those approval steps yourself.

If your agent cannot configure the connection, use the instructions for your client below.

Claude desktop and Claude Code

Install the xpnAI connector

1. Open xpnAI in Claude’s connector directory .
2. Follow the prompts to install and connect xpnAI to your Claude account.
3. Sign in to xpnAI, choose your Workspace and approve the requested permissions as described below.
4. Enable the xpnAI connector in your conversation, then ask Claude which Workspace and organisations it can access.

If your organisation restricts connectors, ask your Claude organisation administrator to enable xpnAI. If xpnAI is already installed, connect the existing listing.

In a local Claude Code desktop session, use + > Connectors beside the prompt box to select the connection. Ask Claude which connectors it can use if xpnAI is not appearing. See Claude Code desktop connections .

If you use Claude Code in a terminal

Run this command to add xpnAI:

claude mcp add --transport http --scope user xpnAI "https://api.xpnai.app/mcp"

Open Claude Code and enter /mcp. Select the xpnAI server and follow the authentication prompt. Complete the xpnAI approval in your browser, then return to Claude Code. User scope makes the connection available across your local projects.

For the most up-to-date process on connecting an MCP server in Claude Code, see Claude Code’s MCP instructions .

ChatGPT desktop and Codex

For a desktop version with MCP servers in Settings:

1. Open Settings > MCP servers and select Add server.
2. Name the server xpnAI, choose Streamable HTTP and enter https://api.xpnai.app/mcp.
3. Save it and select Restart when prompted.
4. Select Authenticate if the server requires sign-in. Complete the xpnAI approval in your browser.
5. Start a new conversation and use /mcp to check the connection.

If you use the Codex terminal client, run:

codex mcp add xpnAI --url "https://api.xpnai.app/mcp"
codex mcp login xpnAI

The second command starts the browser sign-in. Return to Codex afterwards and start a new task.

For the most up-to-date process on connecting an MCP server in Codex or ChatGPT desktop, see OpenAI’s MCP connection instructions .

ChatGPT in a browser

The web setup uses a custom app, configured separately from Codex.

If your organisation already provides an xpnAI app, connect it from Settings > Apps, sign in and select it in your conversation.

Custom MCP apps require developer mode and an account that allows it. Your organisation may restrict app creation or require administrator approval.

1. Open Settings > Security and login and enable Developer mode, when your account permits it.
2. Open ChatGPT’s plugins page and use the plus button to create a developer-mode app.
3. Enter xpnAI, use https://api.xpnai.app/mcp as the server URL and choose OAuth authentication. Complete the xpnAI authorization and app creation steps shown.
4. In a conversation, choose Developer mode from the plus menu and select the xpnAI app. Follow your organisation’s approval process to make it available to other members.

For the most up-to-date process on connecting an MCP server in ChatGPT web, see OpenAI’s developer-mode instructions .

Cursor and Grok Bot

Ask Cursor or Grok Bot to connect:

Read and use https://help.xpnai.app/connect.md
to connect this assistant to my existing xpnAI Workspace.

Your assistant should check its available connection controls, reuse a suitable connection or add xpnAI, and start sign-in. Grok Bot should use the Cursor instructions when its connection controls support that flow.

If you configure Cursor yourself, add a remote Streamable HTTP MCP server named xpnAI with the address https://api.xpnai.app/mcp, then use its connection controls to authenticate. Follow Cursor’s current MCP instructions  for your interface. Complete the xpnAI approval steps below.

If sign-in is missing or blank

Tell your assistant that the xpnAI sign-in prompt is missing and include the error shown. Ask it to follow the Cursor troubleshooting instructions .

Stay on MCP connection setup. You do not need to create another Workspace, restart your trial or reconnect Xero because a sign-in prompt is missing.

An unreachable-server message can have several causes. Your assistant should inspect the connection error and use the client’s supported reconnect or authentication controls. If registration was rejected, the troubleshooting instructions describe a supplied client ID fallback for clients that support it. You still sign in and approve access normally.

Other MCP clients

Choose a remote or Streamable HTTP server connection, enter https://api.xpnai.app/mcp and use the client’s browser-based OAuth sign-in. If the client offers only an API key field, check its instructions for OAuth support before continuing. You do not need an xpnAI API key for this connection.

Approve the connection in xpnAI

When the assistant opens xpnAI:

1. Select Sign up or Sign in, then continue with Google or Microsoft. If you already belong to a Workspace, you go directly to the assistant’s permissions page. Otherwise, the setup steps guide you through naming your Workspace, starting your free trial, connecting Xero and confirming the organisations to sync. Assistant permissions is the final setup step. Your first import continues in the background; you do not need to wait for a sync status screen.
2. Check the requesting assistant’s name.
3. Choose the Workspace you want it to access.
4. Choose the optional permissions you want to grant. Read and export access is required. Expand Connection details if you need to check where the browser will return.
5. Select Allow access, or Cancel to return to your assistant without granting access.

Every connection offers access to read and export finance data, create draft manual journals, create draft bills and sales invoices, and change accounts or tracking in Xero. Read and export access is selected and required. The three write permissions are separate and unchecked by default. Select only the changes you want the assistant to make. Leave all three unchecked for read-only access. Draft bill and invoice permission includes intercompany recharge pairs.

Your choices apply to this connection. To change permissions later, revoke the connection in Connections > MCP, reconnect from your assistant and choose the permissions again.

Your connection keeps its chosen Workspace when you switch Workspaces in the xpnAI browser. To use another Workspace, add a separate assistant connection and choose it during approval. Use a recognisable connection name in your assistant.

Check that it works

Ask your assistant:

Use xpnAI to show the connected Workspace, its Xero organisations, import status and last successful sync times.

Check the Workspace and organisations before asking for analysis or changes. Continue with Work with your finance data for example requests and limits.

The assistant’s Workspace context includes only organisations selected for syncing. Organisations shown as Available are excluded. Sync-enabled organisations remain listed if disconnected, with their import status and last successful refresh time, so the assistant can identify stale data.

The assistant should use get_context to verify access. Your first Xero import can continue while you connect; follow its progress in Connections > Xero. A pending import or empty organisation list does not mean your balances are zero.

Tools have readable names such as Prepare a journal plan and View journal audit evidence. Some clients show their technical identifiers, such as prepare_journal_plan, alongside these names. Both refer to the same tool.

View or revoke your connections

In xpnAI, open Connections > MCP and find Connected assistants. The list shows your connections to the Current Workspace, with their names, dates, expiry and status. Switch Workspace to manage connections to another Workspace.

Workspace Administrators see Mine by default. Select All users to manage other members’ connections, including each connection’s user name and email. Other members see only their own connections.

The Follow the connection guide link beneath the MCP server URL opens this guide. Copy the Agent prompt above the URL to have your assistant connect to your current Workspace, or copy the server URL to configure the connection yourself. A notification confirms the copy. If copying fails, the notification explains how to copy manually. The separate Connected assistants section lists existing connections.

Select Revoke access beside a connection, then confirm Revoke access in the dialog to stop future requests and token renewal. Select Cancel to keep the connection. Revoked connections disappear from the list and cannot be restored. Workspace Administrators can also revoke other members’ connections to the Current Workspace. To connect again later, reconnect from the assistant and approve a new connection.

Removing your Workspace membership stops future requests. If you no longer belong to the Workspace, ask one of its Workspace Administrators to revoke an old connection.

Revoking access cannot remove files already downloaded. Export links already issued keep working until they expire.

Troubleshooting

Assistant connection menus change over time. The OpenAI setup instructions were checked against its documentation on 14 September 2026.