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

Dunning

Email

Platform

Tasking

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