Connect Cursor

Cursor reads MCP servers from an mcp.json file — one for you, one per project. A remote server needs nothing but a URL.

Add the server

Open Customize in the sidebar to manage MCP servers, or write the file directly:

{
  "mcpServers": {
    "invoia": {
      "url": "https://invoia.io/api/mcp"
    }
  }
}

There is no type field for a remote server — a url is what makes it remote. Reload Cursor, find invoia in the MCP list, and log in. Cursor runs the OAuth flow itself — the browser opens an invoia.io sign-in and the consent screen, and that is the only way Invoia authenticates an MCP client.

Cursor's own agents cannot connect

Signing in is a browser step, and Invoia's MCP server accepts no other credential — there is no headless variant of this entry. A background agent, a CI job or anything else running without a person at a browser has no way to authenticate.

Use the REST API for that work: a Bearer key on /api/v1, no consent step, the same product underneath. A REST integration you already run is unaffected.

Verify it works

In Agent mode:

@invoia list the retainers that renew this month

Cursor shows the tool calls it made. If it returns real series names, the connection is live — and it returns your retainers, the ones you are assigned to, with a line saying how many sit outside that view. See Auth and scopes for how to widen it.

Mind the tool budget

Invoia registers 28 tools on a full-scope connection — sixteen reads, eleven plan_*, and commit. Cursor caps the total number of tools it will send to the model across all servers (commonly reported at 40), so Invoia alone is most of it.

If tools start disappearing, you have three levers: disable other servers in Customize, use a tool allowlist to trim the ones you never call, or approve only mcp:read at the consent screen — that registers sixteen tools and nothing else, which is enough for every question that does not write.

Troubleshooting

• Tools do not appear at all — check the JSON parses and that the server is toggled on. A disabled server does not load or show up in chat.
• Every call 401s — the token expired and the refresh failed, or the grant was revoked. Log out and back in from the MCP settings.
• 406 Not Acceptable — something between Cursor and Invoia is stripping the Accept header. Streamable HTTP requires both application/json and text/event-stream; a proxy that rewrites it breaks the transport before the credential is read.
• The agent proposes but never writes — that is the design. A plan_* tool returns a plan; you approve, and it calls commit. See The propose → commit contract.
• A name matches several rows — the error lists the candidates. Pick one, or address it as ext:your-id.