MCP server
Connect Claude, ChatGPT or your own agent to a store's Invoice Falcon data over MCP, with OAuth sign-in or a connector key.
Last updated
Invoice Falcon runs an MCP server that reaches every API v3 action. AI apps such as Claude and ChatGPT connect to it as a custom connector, and your own agents can call it directly.
- Server URL:
https://app.invoicefalcon.com/api/v3/external/mcp - Transport: streamable HTTP,
POSTonly (aGETanswers405). Batches hold up to 10 requests. - Manifest:
/api/v3/mcp.json, with the tool list and auth details.
Who can connect
Section titled “Who can connect”The same stores that can use API v3: the store must be on the current Invoice Falcon dashboard and on a paid plan. Otherwise the sign-in page and every call refuse with the reason.
The server has three tools instead of one per action, so an agent’s context stays small however many actions there are.
| Tool | What it does |
|---|---|
search |
Finds actions by keyword across their paths, names, descriptions and aliases, for example send invoice or plan and usage. With 3 or fewer matches it includes each action’s request schema. An empty query lists everything. |
execute_read |
Runs a GET action. path must be concrete, with real ids in place of :placeholders. |
execute_write |
Runs a POST, PATCH or DELETE action. |
Each tool’s input schema is in the MCP tool reference.
An order name can go in a path as is (/orders/#1042); you don’t need to encode # here. Permanent changes still need confirm: true after the merchant agrees. See Confirming permanent changes.
Authentication
Section titled “Authentication”The MCP server refuses the REST API key on purpose: a key pasted into a chat app shouldn’t be the one that opens the whole API. It accepts:
-
OAuth 2.1 sign-in. Claude and ChatGPT connectors do this by themselves. Discovery documents:
https://app.invoicefalcon.com/.well-known/oauth-authorization-serverhttps://app.invoicefalcon.com/.well-known/oauth-protected-resource
Clients register dynamically. The sign-in page asks the merchant for the store’s connector key and grants one full-access token; there are no scopes to pick.
-
The connector key itself, for scripts and agents you run:
Authorization: Bearer <connector key>(orX-Auth-Token).
The merchant finds the connector key in the app under Settings > Integrations > AI connectors. Resetting it disconnects every connected AI app at once, including those that signed in with OAuth. The REST API key is separate and keeps working.
Connect Claude or ChatGPT
Section titled “Connect Claude or ChatGPT”- In Claude or ChatGPT, open Settings > Connectors and add a custom connector.
- Paste the server URL,
https://app.invoicefalcon.com/api/v3/external/mcp. - The app opens the Connect [app] to Invoice Falcon page. Paste the connector key and click Allow.
Merchant-facing steps, with troubleshooting, are in the help center: Connect Claude or ChatGPT.
Call it from your own agent
Section titled “Call it from your own agent”curl -s https://app.invoicefalcon.com/api/v3/external/mcp \ -H "Authorization: Bearer $INVOICE_FALCON_CONNECTOR_KEY" \ -H "Content-Type: application/json" \ -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "search", "arguments": {"query": "send invoice"}}}'curl -s https://app.invoicefalcon.com/api/v3/external/mcp \ -H "Authorization: Bearer $INVOICE_FALCON_CONNECTOR_KEY" \ -H "Content-Type: application/json" \ -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "execute_read", "arguments": {"method": "GET", "path": "/account/plan"}}}'Claude Code:
claude mcp add --transport http invoicefalcon https://app.invoicefalcon.com/api/v3/external/mcp \ --header "Authorization: Bearer $INVOICE_FALCON_CONNECTOR_KEY"Rate limits
Section titled “Rate limits”40 points per store every 60 seconds, the same budget as the REST API. MCP requests are POSTs, so each tools/call costs 2 points, reads included: about 20 tool calls a minute. A batch is charged per tools/call in it.
Other ways in for agents
Section titled “Other ways in for agents”Thanks for letting us know.
Still stuck? Ask Quinn or chat with support