Skip to content

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, POST only (a GET answers 405). Batches hold up to 10 requests.
  • Manifest: /api/v3/mcp.json, with the tool list and auth details.

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.

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:

  1. OAuth 2.1 sign-in. Claude and ChatGPT connectors do this by themselves. Discovery documents:

    • https://app.invoicefalcon.com/.well-known/oauth-authorization-server
    • https://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.

  2. The connector key itself, for scripts and agents you run: Authorization: Bearer <connector key> (or X-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.

  1. In Claude or ChatGPT, open Settings > Connectors and add a custom connector.
  2. Paste the server URL, https://app.invoicefalcon.com/api/v3/external/mcp.
  3. 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.

Terminal window
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"}}}'
Terminal window
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:

Terminal window
claude mcp add --transport http invoicefalcon https://app.invoicefalcon.com/api/v3/external/mcp \
--header "Authorization: Bearer $INVOICE_FALCON_CONNECTOR_KEY"

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.

  • skill.md: the whole API as one document written for AI agents, with recipes.
  • /llms.txt: points agents at the documents above.
Was this page helpful?

Still stuck? Ask Quinn or chat with support