Connect an AI agent to PolyAccounts

Start with your company

Create a company account and import your actual books. Your team and agents work with the same general ledger and reports. A company administrator controls each agent connection.

Try the integration before creating an account

The public agent kit includes an invented demonstration company, a local MCP server, an expense-review example and reusable review workflows. It uses Node.js 20 or later and has no runtime dependencies. The demo needs no login, database, API key or network connection after installation.

Download the demo desktop extension for an MCPB-compatible client, or use the pinned package below with a client that supports stdio MCP. The demo is intentionally read-only. Full company write access is provided by the separate hosted connector.

npx -y --package=https://github.com/andrewblount/polyaccounts-agent-kit/releases/download/v1.2.2/polyaccounts-mcp-1.2.2.tgz polyaccounts-demo   # synthetic read-only demo
npx -y --package=https://github.com/andrewblount/polyaccounts-agent-kit/releases/download/v1.2.2/polyaccounts-mcp-1.2.2.tgz polyaccounts-mcp                        # full connector. call create_sandbox first

Or let the agent create its own sandbox

A sandbox is a synthetic, isolated company with a starter chart of accounts, two months of invented activity, a seven-day full-access agent credential and a browser sign-in. An agent creates one with a single POST, or by calling the create_sandbox tool in the stdio connector when no credential is configured. No account, approval or human step is required.

Sandboxes must never hold real records. They are soft-deleted at expiry. Quotas are published on the limits page.

curl -X POST https://polyaccounts.com/api/agents/sandbox -H "Content-Type: application/json" -d '{"language":"en","currency":"USD"}'

Connect your company

An administrator opens Settings, then AI agents, and issues a company-scoped credential. Store the credential in your client’s protected secret configuration or in a local token file. Never paste a credential into a prompt, issue, public repository or support message.

Install the hosted connector extension and enter that credential in its sensitive configuration field. Or download the standalone connector, set POLYACCOUNTS_TOKEN_FILE to your protected token file, and run it with Node.js. No source checkout or direct database access is required.

Clients that support remote MCP connect to https://polyaccounts.com/mcp with OAuth 2.1. The client registers itself, a company administrator signs in and approves the connection once, and the client receives an access token that is an ordinary 90-day agent credential plus a refresh token. Clients that support only local stdio use the downloadable bridge with a token file. Both paths issue the same company-scoped credential.

{
  "mcpServers": {
    "polyaccounts": {
      "command": "node",
      "args": ["/absolute/path/polyaccounts-mcp.mjs"],
      "env": { "POLYACCOUNTS_TOKEN_FILE": "/absolute/path/agent-token" }
    }
  }
}

Verify a useful connection

Initialize MCP and request tools/list. Call accounting_context to confirm the authorized company, then profit_loss, balance_sheet and ledger_entries for an explicit period. Keep exact decimal strings and follow all pagination cursors using the same filters.

A successful accounting tool response verifies the connection. Listing tool metadata alone does not. Before attempting a write, inspect the tool schema and supported operations. The hosted catalog documents create, update, soft-delete and accounting workflows.

Resolve common connection problems

For an authentication error, check that the credential is current, belongs to the intended company and has not been revoked. An administrator can issue a replacement. Do not work around company boundaries by using an operator database connection.

For an uncertain write response, inspect the receipt and retry only with the same idempotency key. A revision conflict means the record changed since you read it. Retrieve the current record and reconsider the change. A period lock or payment restriction requires the documented accounting workflow.