MCP Server

Billabex exposes a Model Context Protocol (MCP) server so AI tools can access Billabex data using OAuth 2.1. This guide explains discovery, authorization, available tools and resources, and how to connect.

MCP Endpoint

The MCP server uses Streamable HTTP (stateless):

POST [baseURL]/mcp

OAuth Discovery Flow

MCP clients follow RFC 9728 (Protected Resource Metadata) and RFC 8414 (OAuth Authorization Server Metadata):

1. Call POST /mcp without a token.
2. The server responds with WWW-Authenticate including resource_metadata and scope.
3. Fetch the resource metadata URL to discover authorization_servers and scopes_supported for /mcp.
4. Fetch the authorization server metadata to locate the authorization and registration endpoints.

Example 401 Response

The MCP server returns:

WWW-Authenticate: Bearer resource_metadata="[baseURL]/.well-known/oauth-protected-resource", scope="mcp:read mcp:write"

Protected Resource Metadata (Path-Aware)

For /mcp, request:

[baseURL]/.well-known/oauth-protected-resource/mcp

The response includes:

{
  "resource": "[baseURL]",
  "authorization_servers": ["[baseURL]"],
  "scopes_supported": ["mcp:read", "mcp:write"],
  "bearer_methods_supported": ["header"]
}

Authorization Server Metadata

GET [baseURL]/.well-known/oauth-authorization-server

This returns the authorization_endpoint, token_endpoint, and registration_endpoint needed for OAuth 2.1 + PKCE.

Scopes

MCP uses two scopes:

Consent Behavior

If an authorization request omits the scope parameter, Billabex defaults to mcp:read mcp:write for MCP clients.

Protocol Details

• Transport: Streamable HTTP (stateless mode).
• Authentication: Authorization: Bearer <token> header (required).
• Rate limiting: 300 requests/minute per token (sliding window).
• CORS header: Clients may send Mcp-Protocol-Version header.

Resources

MCP resources provide metadata that AI tools can read to understand Billabex capabilities.

These resources help AI agents understand:

• About: What Billabex is, how it helps businesses manage invoice collection
• Concepts: Domain model including invoices, accounts, customer balances, communications, and tasks
• Workflow: Standard dunning workflow from invoice overdue to payment recovery

Prompts

MCP prompts provide business-oriented templates for AI agents to perform common tasks. Unlike tools, prompts use human-readable parameters (account names, organization names) instead of technical IDs.

How Prompts Work

1. User provides names: You call a prompt with an account name like “Acme Corp” instead of a UUID
2. Agent resolves IDs: The prompt instructs the AI agent to use tools like list-accounts and list-organizations to find the matching IDs
3. Agent gathers data: The agent calls multiple tools to gather relevant data
4. Agent presents results: Results are formatted naturally without exposing technical IDs

Example: Financial Snapshot

{
  "name": "financial-snapshot",
  "arguments": {
    "organizationName": "My Company",
    "period": "30days"
  }
}

The agent will:

1. Use list-organizations to find “My Company”
2. Use list-customer-balances to get outstanding balances
3. Use list-invoices to find upcoming due invoices
4. Present a formatted overview of your financial position

Tools Reference

Tools are grouped by domain. Read tools require mcp:read; Write tools require mcp:write.

Tool outputs include human-friendly fields such as displayName and summary where available. Prefer those fields for user-facing responses and keep IDs for follow-up tool calls.

All tools include annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) to help AI agents understand their behavior.

Invoicing

A disabled contact is never contacted proactively by the agent. Re-enabling one is a human decision, so set-contact-enabled should not be used to undo a disable the client asked for.

create-contact, update-contact and upsert-contact take a phones list of { number, countryCode? }. A number starting with + or 00 carries its own country code; any other number is national and requires countryCode (ISO 3166-1 alpha-2), because Billabex never guesses a country. Contacts are returned with phones: [{ number, type, country, origin }], where type (Mobile / Landline / Unknown) and country are derived from the number itself and read-only. Writing phones replaces only what a human entered, never the numbers a connector brought (origin: "Connector"); omit the field to leave everything alone, send [] to clear the manual ones. Only a French mobile can receive an SMS. See Contacts for the full model.

Documents created by create-invoice and create-credit-note carry the Mcp channel, distinct from the PublicApi one the REST API stamps. They can live on an organization that is also synced with one or more connectors: see Sources for why an account’s source never tells you where one of its documents came from.

list-invoices and list-credit-notes return accountPaymentMethod as DIRECT_DEBIT, BANK_TRANSFER, or null. The value is read from the account when the list is requested, so changing the account does not require updating each document.

Account tools expose accountType as Professional, Consumer, or Unknown. create-account and update-account accept the same field. Omit it at creation to infer Professional from a legal identifier, otherwise the account remains Unknown. A standard connector controls the value and cannot be overridden through MCP; a Custom source remains editable. Consumer accounts are not checked against BODACC, while their SIREN and VAT number, if present, remain available through the API.

Dunning

list-communications reads a pre-joined projection and filters by account, type, delivery status (bounced, complained) and date range on the server. Prefer it over paging the incoming and outgoing lists separately.

Email

Platform

Both organization tools return credits, the prepaid balance that pays for the SMS and postal letter reminders Billabex sends. See Credits below.

They also return the two effective first-reminder rules, firstReminderDelayForDirectDebit and firstReminderDelayForBankTransfer, each { days, direction } with direction being BEFORE or AFTER the due date, or null when neither an override nor firstReminderDelayDays is set. update-organization-settings writes them under the same names: an absent key leaves that mode alone, an explicit null records that the mode has no rule of its own and falls back on firstReminderDelayDays. An account whose payment method is unknown follows firstReminderDelayDays alone, never either of these two.

They also return logo, the image uploaded for the organization, or null. null does not mean no logo is shown: with none uploaded, one is derived from the organization’s email domain at display time and nothing is stored. set-organization-logo takes a base64 PNG, JPEG or WebP up to 2 MB, or file: null to remove it. The real file signature is checked, not the declared type, so an SVG is refused.

Tasking

Credits

get-organization and list-organizations return a credits field: the prepaid balance that pays for the SMS and postal letter reminders Billabex sends on your behalf. Emails are free and never consume it.

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Acme Corporation",
  "credits": 250
}

At zero, SMS and letters stop going out; email reminders keep running. Nothing else in the API signals that, which is why the balance is worth reading if you build a dashboard or an alert on top of Billabex.

The field is read-only, but send-outgoing-letter spends it after rendering the selected invoices and credit notes. Call preview-outgoing-letter first to obtain the exact page count and credit price without spending anything. send-outgoing-communication still sends a free email. Topping the balance up is not self-service; Billabex handles it manually.

Pagination

Tools returning lists use cursor-based pagination:

• Parameters: first (items per page, max 100), after (cursor).
• Response: nodes array + pageInfo.endCursor.

Notes

• OAuth is required for all MCP access.
• Tokens must be sent in the Authorization: Bearer <token> header.
• Rate limiting applies to MCP requests (300/min per token).
• update-outgoing-communication accepts message in markdown. Do not include a signature; the platform renders HTML/text and appends the agent signature automatically.

Next Steps

• OAuth Authentication
• OAuth Scopes