---
name: iblai-connect-xero
description: "Read and write Xero data through the Xero Accounting API and expose it to an ibl.ai agent as an MCP tool. Use when the user asks an agent to work with Xero data, or to set up a Xero MCP connection on ibl.ai."
metadata:
  kind: guide
---

# Xero connector for AI agents

> A starting point maintained on ibl.ai at https://ibl.ai/developer/connectors/xero — not part of the iblai/vibe repository. Checked against Xero's documentation on October 20, 2026; test it against your own Xero setup before you rely on it.

Cloud accounting software for small businesses. A Xero organisation holds contacts, invoices, bills, payments, bank transactions, manual journals, the chart of accounts, tax rates and reports; some regions also hold payroll.

## Auth & conventions

- **API:** Xero Accounting API (REST). REST endpoints for a Xero organisation: Invoices, Contacts, Payments, BankTransactions, ManualJournals, Accounts and Reports. Paged list endpoints return 100 records by default (pageSize up to 1,000).
- **Base URL:** https://api.xero.com/api.xro/2.0/
- **Access:** Public, self-serve. Developers register an app in the Xero Developer portal. Custom connections (client credentials for a single organisation) are a premium integration option; standard apps use the authorization code or PKCE flow.
- **Auth:** OAuth 2.0 authorization code; OAuth 2.0 authorization code with PKCE; OAuth 2.0 client credentials (custom connections). Users authorize the app; request offline_access for a refresh token. Access tokens last 30 minutes. GET https://api.xero.com/connections lists authorized organisations; send the tenant ID in the xero-tenant-id header on every call.
- **Limits:** Per organisation: 5 concurrent calls, 60 calls per minute, and a daily cap (1,000 on Starter, 5,000 on higher tiers); 10,000 calls per minute per app across organisations. HTTP 429 sends Retry-After; X-MinLimit-Remaining and X-DayLimit-Remaining headers.
- Keep Xero credentials in environment variables or the ibl.ai credential store. Never print a token in chat and never commit one to a file.
- Destructive or outward-facing calls are marked **Confirm with the user first** — do.

## Reads

- **Invoices** — GET /Invoices lists sales invoices and bills with line items; supports page and pageSize.
- **Contacts** — GET /Contacts lists customers and suppliers; paged with page and pageSize.
- **Payments** — GET /Payments lists payments applied to invoices and credit notes.
- **Bank transactions** — GET /BankTransactions lists spend and receive money transactions.
- **Reports** — Report endpoints such as Profit and Loss, Balance Sheet, Trial Balance and aged receivables/payables.

## Writes

- **Create invoice** — Create draft or authorised invoices and bills through the Invoices endpoint.
- **Create or update contact** — Add or edit customers and suppliers through the Contacts endpoint.
- **Record payment** — Apply a payment to an invoice through the Payments endpoint; changes the ledger. **Confirm with the user first.**
- **Manual journal** — Post a manual journal through the ManualJournals endpoint. **Confirm with the user first.**

## Expose it to an ibl.ai agent (MCP)

Xero publishes an official MCP server, Xero Developer Remote MCP Server (https://developer.xero.com/documentation/guides/remote-mcp/overview). Register it below as-is, or host your own server that wraps the calls in this skill.

First install the ibl.ai platform skills and connect your organization (writes `IBLAI_ORG`, `IBLAI_USERNAME` and `IBLAI_API_KEY` to `.env`):

```bash
npx skills add iblai/vibe --all
# then, in your coding agent:
/iblai-api-login
```

Every call below sends `Authorization: Api-Token $IBLAI_API_KEY`.

1. **Register the server** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-servers/` with `name`, `url`, `transport` (`sse` | `websocket` | `streamable_http`) and `auth_type` (`none` | `token` | `oauth2`). Capture the returned `id`.
   - Xero supports per-user OAuth: `auth_type=oauth2` with `auth_scope=user` and a linked `oauth_service` makes each person connect their own account in the chat. It needs an `auth_{provider}` credential in the organization's credential store first.
2. **Create the connection** — `POST https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mcp-server-connections/` with `server`, `scope` (`platform` | `mentor` | `user`), `auth_type`, and either `credentials` + `authorization_scheme` or a `connected_service` id for OAuth. Credentials are masked on read; never send a masked value back.
3. **Enable it on the agent** — `GET https://api.iblai.app/dm/api/ai-mentor/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/mentors/{agent_id}/settings/`, add `mcp-tool` to `tool_slugs` and the server id to `mcp_servers`, then `PATCH` the full lists back. They are replaced, not merged.

Full reference: https://ibl.ai/developer/platform/mcp/mcp-connections and the `/iblai-api-agent-mcp` skill.

## Example prompts

- "Show all Xero invoices that are overdue, grouped by customer"
- "Create a draft invoice in Xero for Blue Sky Ltd for 5 units of item WIDGET-01"
- "Run the Profit and Loss report for last month and summarize the biggest expense lines"
- "List supplier bills due in the next 14 days"

## Guardrails

- Holds business financial records and contact personal data; payroll regions add employee pay and tax details (payroll PII). Treat as confidential; request the narrowest granular scopes.
- Request the narrowest Xero scopes or role the task needs, and prefer a read-only credential for agents that only answer questions.
- Return the fields the user asked for, not whole records; do not paste personal data into chat that the user did not request.
- Before any write, show the user exactly what will change and wait for a yes.
- Respect the documented limits above: page through results and back off on rate-limit responses instead of retrying in a loop.

## References

- Xero AI toolkit (MCP servers): https://developer.xero.com/ai
- Xero MCP server (GitHub): https://github.com/XeroAPI/xero-mcp-server
- Xero OAuth 2.0 API limits: https://developer.xero.com/documentation/guides/oauth2/limits/
- Xero Developer Remote MCP Server: https://developer.xero.com/documentation/guides/remote-mcp/overview
- This connector on ibl.ai: https://ibl.ai/developer/connectors/xero
- ibl.ai MCP server connections: https://ibl.ai/developer/platform/mcp/mcp-connections