MCP servers for AI agents (x0 + xerosim)

Two local MCP servers teach agents the x0 OData API and the Xero API simulator before they call your live endpoints. x0 cannot see MCP tool calls on your machine — it only sees the HTTP requests your agent makes afterward. Customers with MCP configured typically make fewer discovery calls (/Tables, /$metadata) and more targeted reads ($select, $filter).

Which MCP do I need?

Most production agents need x0 only. Use xerosim while building integrations before connecting real Xero.

What the MCP gives your agent

Both servers expose tools (and browseable resources) with:

• Every table / resource — name, kind, primary key, OAuth/API scope
• Field-level schema — name, data type, official description, example value
• Linkages — foreign keys (ContactID → Contacts), *_Table line grains, Attachments parent types
• Schema diagram — mermaid ER flowchart (get_schema_diagram) to show users or paste into their docs
• Agent rules — auth, cache (refresh=true sparingly), multi-tenant headers, query options
• Xero quirks — journals tier gate, pagination traps, scope consent failures
• Write rules (x0) — Accounts / Contacts / Invoices preflight checks

Your agent should call list_tables / describe_table (or list_resources / describe_resource for sim) once per session, then query x0 with $select — not re-probe /$metadata on every turn.

Install

From your x0 shim checkout (or the copy we ship in docs):

cd shim
python3 -m venv .venv-mcp
.venv-mcp/bin/pip install -r agent_mcp/requirements-mcp.txt

Requirements: Python 3.10+, network only for optional live query_odata / query_sim tools. Schema tools work offline.

Cursor configuration

Project or user mcp.json (paths adjusted to your machine):

{
  "mcpServers": {
    "x0": {
      "command": "/path/to/x0/shim/.venv-mcp/bin/python",
      "args": ["-m", "agent_mcp.x0"],
      "cwd": "/path/to/x0/shim",
      "env": {
        "X0_API_BASE_URL": "https://api.x0.co.nz",
        "X0_API_KEY": "x0_live_<token_id>.<secret>"
      }
    },
    "xerosim": {
      "command": "/path/to/x0/shim/.venv-mcp/bin/python",
      "args": ["-m", "agent_mcp.xerosim"],
      "cwd": "/path/to/x0/shim",
      "env": {
        "XEROSIM_BASE_URL": "https://sim.dev.x0.co.nz",
        "XEROSIM_BEARER_TOKEN": "<sim-oauth-access-token>"
      }
    }
  }
}

Copy the full example from shim/agent_mcp/mcp-config.example.json.

Security

• Put X0_API_KEY in the MCP server env block — never in chat or tool arguments.
• Issue a key in the portal with minimum scopes your agent needs.
• Optional live tools: query_odata (x0), query_sim (xerosim). Schema-only workflows need no key.

Claude Desktop / other MCP clients

Same pattern: stdio transport, command = venv python, args = -m agent_mcp.x0 or -m agent_mcp.xerosim, cwd = shim directory.

Recommended agent workflow (x0)

1. list_tables — see entity sets your key can access (match with portal scopes).
2. describe_table for each entity you will use — fields, examples, PK, summary_only_fields.
3. get_linkages — join paths (e.g. Invoices → Contacts).
4. get_schema_diagram — mermaid flowchart for the user (detail=overview or full).
5. get_agent_rules — especially cache and auth categories.
6. GET /odata/v1/Accounts?$select=Code,Name (via your HTTP client or optional query_odata) — targeted reads.
7. Use ?_Table entity sets when you need one row per line item (Invoices_Table, not nested LineItems in code).

Avoid on every turn:

• GET /odata/v1/$metadata
• GET /odata/v1/Tables (unless scopes changed)
• Full Invoices without $select
• refresh=true on scheduled loops

Cache, gzip, and freshness (agent essentials)

Call get_cache_policy (or get_agent_rules category cache / transport) before assuming live data.

x0 MCP tools reference

Resources: x0://tables, x0://rules, x0://linkages, x0://schema-diagram

xerosim MCP tools reference

Resources: xerosim://resources, xerosim://rules

How x0 knows MCP is helping

MCP runs locally — we do not receive MCP tool invocations. We infer agent quality from your x0 API traffic:

Your portal Dashboard → Agent API efficiency shows these buckets and a simple score. Staff see aggregates on Mission Control → Performance.

Validate your install

cd shim
./scripts/validate_mcp.sh

Or with pytest: pytest tests/test_mcp_servers.py tests/test_agent_mcp.py -q

Troubleshooting

Related

• AI agents — HTTP discovery order, Bearer auth
• OData — $filter, $select, scopes
• Data schema — dashboard diagram + mermaid
• Data freshness — cache and refresh=true
• Xero API simulator — hosted sim URL and x0 wiring
• Repo: shim/agent_mcp/README.md (operator notes)