AI Agent Integration (MCP)

How you connect to NP Ledger depends on which AI Assistant you use

There are two ways to connect to NP Ledger's MCP tool. The app you use determines which way you'll connect. This guide has the steps for each.

MCP is short for Model Context Protocol. It is the standard AI assistants use to work with other apps.

Signing in connects through a screen we show you, so there is nothing to copy. A token is for tools where you edit a config file or set a header yourself.

After you connect, you manage everything on the AI Agent Integration page. Choose Settings, then AI Agent Integration. Only an Admin or Owner can open it. The last two sections of this guide list every tool your AI assistant can use.

Connect with sign-in (claude.ai, Claude Desktop, Claude Cowork, ChatGPT)

You sign in to NP Ledger from inside your AI assistant. Your AI assistant calls this a connector. It is how the AI assistant links to another app.

1. Check that you have an NP Ledger account that belongs to an organization. Sign in at npledger.com. If you can open your organization's books, you're ready. If you don't have an account yet, sign up at npledger.com and finish setting up your organization, then come back to this step.

   • Any role can connect. Your role sets what your AI assistant can do. Owners, Admins, Accountants and Members can look things up and record transactions. Viewers can only look things up.
   • To see or disconnect the connection afterwards, you must be an Admin or Owner. It is under Settings, then AI Agent Integration.

2. Open your AI assistant's connectors.

   • claude.ai or Claude Desktop: choose Customize, then Connectors, then + Add.
   • Claude Team or Enterprise plan: the Owner of your Claude organization adds the connector first, under Organization settings, then Connectors. You then choose Connect on it.
   • ChatGPT: find NP Ledger in the plugin directory and choose Connect. On a ChatGPT Business or Enterprise plan, your ChatGPT admin may need to enable it first. ChatGPT already knows NP Ledger's name and web address, so skip step 3.

3. Type NP Ledger's name and web address. Your AI assistant shows a box for each. In the name box, type NP Ledger. In the web address box, type the address below. Then choose Continue.

   https://mcp.npledger.com/v1/
   

   If your AI assistant says NP Ledger is already added, open the one in your list and choose Connect. Or remove it and add it again.

4. Leave the sign-in settings as they are. If a second window opens with sign-in settings, including an Advanced area, leave every setting as it is and choose Add. Your AI assistant fills them in. If no second window opens, go on to step 5.

5. Choose Connect when your AI assistant says you are not connected to NP Ledger yet. From here you have about 10 minutes to finish steps 6 and 7.

6. Sign in to NP Ledger when your AI assistant sends you to our sign-in page. Use the email and password you use for NP Ledger.

7. Check the "Connect your AI assistant" screen, then choose Allow access.

   • If you belong to one organization, the screen names it.
   • If you belong to several, the screen lists them with your role in each. Pick the one your AI assistant should use.
   • The screen says whether your AI assistant can only read, or can also record. It gets the permissions of your role, and the screen has no read-only switch. To give an AI assistant read-only access, connect as a user whose role is Viewer, or use a token set to Read-only (see the next section).

8. Test the connection. Ask your AI assistant: "What organization am I connected to?" It answers with your organization's name, fiscal year and plan. If it doesn't, see If something goes wrong, below.

If you see "Let's start that connection again", nothing went wrong. Start again from step 5.

A sign-in connection belongs to one organization and works until you disconnect it. It can't switch organizations. To use a second organization, add a second connector and pick the other organization on the "Connect your AI assistant" screen.

That is everything for signing in. The next section is for Cursor and scripts.

Connect with a token (Cursor and your own scripts)

1. Sign in to NP Ledger as an Admin or Owner. Choose Settings, then AI Agent Integration, or go to npledger.com/settings/integrations/mcp/

2. Name the token. Under Create New Token, enter a Token name, such as "Cursor".

3. Choose an Access scope. Choose Read-only unless you want your AI assistant to record transactions.

   • Read-only: view data and run reports.
   • Read + Write: also record transactions.

4. Limit what the token can reach (optional). Open Limit this token to specific tools / funds and tick only what the token should reach. Leave everything unticked for full access. A limited token can't call a tool or touch a fund you didn't tick. The last two sections of this guide list the tools.

5. Hold its transactions for approval (optional). To review each transaction before it posts, tick Require admin approval before write actions execute. An Admin or Owner then approves or rejects each one under Pending Approval on the AI Agent Integration page. See Safeguards, below.

6. Choose Generate Token.

7. Copy the token now. We show it once. Store it in a password manager. If you lose it, revoke it and make a new one.

8. Give your AI assistant the address and the token. An app that connects with a token needs two things:

   • The web address: https://mcp.npledger.com/v1/ (Streamable HTTP).
   • The token, sent in a header named Authorization, written as the word Bearer, a space, and your token.

   A token typed into the web address (?token=...) is refused, because addresses end up in logs and browser history.

   Where those two go depends on the app, and the app's own help says where. As an example, Cursor's help shows a settings file shaped like the one below. Save it as .cursor/mcp.json in your project, or ~/.cursor/mcp.json for every project. If your project is in git, use ~/.cursor/mcp.json, or add .cursor/mcp.json to .gitignore, so the token is never committed. We copied this shape from Cursor's help and haven't run it ourselves. If Cursor rejects it, follow Cursor's help and keep the address and header above.

   {
     "mcpServers": {
       "np-ledger": {
         "url": "https://mcp.npledger.com/v1/",
         "headers": { "Authorization": "Bearer YOUR_TOKEN_HERE" }
       }
     }
   }
   

9. Test the connection. Ask your AI assistant: "What organization am I connected to?" It answers with your organization's name, fiscal year and plan. If it doesn't, see If something goes wrong, below.

Try recording a donation

To see the books change, ask your AI assistant: "Record a $500 donation from Jane Smith into the General Fund today. Show me a preview first." The preview shows the exact transaction before anything posts. This needs a connection that can record: a Read + Write token, or a sign-in by a user who can record.

Safeguards

On from the start

• Checks on every transaction. A transaction more than a day in the future is refused. So is one in a locked fiscal year. A date more than two years back comes with a warning to double-check it. Spending from a restricted fund has to go to the project linked to that fund.
• Duplicate protection. A transaction nearly identical to one the same connection posted a moment ago is held until the AI assistant confirms it. A real repeat still goes through.
• Runaway-loop protection. After a burst of transactions, the next one is held until the AI assistant confirms. Normal use never gets there.
• An audit trail. Every transaction an AI assistant records shows in the Audit Log with an MCP badge and the connection's name. A token shows its token name. A sign-in connection shows as "AI connector".
• Corrections. An AI assistant can void a transaction, including one it recorded by mistake. It can't void anything reconciled or in a locked fiscal year.

Settings you control

Admins set these under Write Safeguards on the AI Agent Integration page.

A token also has its own approval box and its own tool and fund limits. You set those when you make the token.

Held transactions

When a safeguard holds a transaction, the AI assistant gets a pending_approval answer with an action_id. It can ask get_pending_action_status whether you approved it.

Admins review held transactions under Pending Approval on the AI Agent Integration page. Each one shows the tool, its details, and who asked: the token's name, or the assistant and the person who signed in. Choose Approve to post it or Reject to drop it. A transaction nobody reviews expires after 30 minutes. A waiting transaction from a sign-in connection can't be approved once that connection is disconnected, or once the person who signed in can no longer record in your organization.

Stop an AI assistant

On the AI Agent Integration page:

• Token: under Active Tokens, choose Revoke.
• Sign-in connection: under AI Assistant Connections, choose Disconnect.

Either one cuts off the AI assistant right away.

Each sign-in connection shows which assistant it is (Claude or ChatGPT, for example), who signed in, whether it can only read or can record too, the date it was first connected, and when it was last used. If the connection was made again after the first time, you also see the date access was last approved.

A user can connect more than one assistant to the same organization, and those share a single row. The row names the first one that signed in, and Disconnect cuts them all off. If the row can't tell which assistant it is, it says so and shows the sign-in's client ID, which is what to quote if you ask us for help.

Plan limits

Each time your AI assistant uses one of our tools counts as one call. Calls are counted for each token, and for each sign-in connection. The count starts over on the first day of each month (UTC). The token limit applies to tokens only. See Billing and plans for what each plan costs.

If something goes wrong

"Unauthorized". On the AI Agent Integration page, look under Active Tokens. If your token isn't listed, it was revoked, so make a new one and replace it in your app. If it is listed, check that the header reads Bearer, a space, then the token, and that the token isn't in the web address. For a sign-in connection, connect again from your AI assistant.

"This tool requires a Standard or higher plan". The tool needs a bigger plan than yours. The Needs column above shows which.

"This action requires accountant access or higher". Your role doesn't allow that tool. An admin can change your role. See Roles and permissions.

"Monthly call limit of 200 reached. Resets 2026-10-31." Your number and date will differ. The connection used its calls for the month. The date shown is the last day of the month, and the count starts over the next day. To raise the limit, change your plan. See Billing and plans.

A tool you expected isn't there. Check the plan, the role, and the token's access scope and tool limits.

"Switching organizations is not available over an OAuth connection". A sign-in connection belongs to one organization. Add another connector for the other one.

Transactions held as duplicate_suspected or burst_suspected. The AI assistant should ask you to confirm. If you meant it, tell it to go ahead.

What your AI assistant can look up

Your AI assistant is only offered the tools it can use. That depends on your plan, on the role of whoever connected it, and, for a token, on its access scope and tool limits. The Needs column shows the lowest plan and role for each tool.

Your organization

Funds, programs and grants

Accounts and transactions

Supporters, vendors and pledges

Bills and bank statements

Reports and year end

What your AI assistant can record

Recording needs a Read + Write token, or a sign-in by an Owner, Admin, Accountant or Member. Both also need the plan and role in the Needs column.

Each transaction comes back with the lines it posted: account, debit or credit, and fund. It also comes back with the new balances, and a warning if cash is overdrawn or a fund went negative. When a name was close but not exact, the AI assistant is told which record it used, so it can tell you.

Most recording tools can show a preview first. A preview shows the transaction the tool would record and posts nothing. These four cannot: match_bank_statement_line, upsert_supporter, void_transaction and switch_org.

Money in

Money out

Moving and matching

Supporters

Fixing a mistake

Organization