Orvion
Get started
Developer Guides
Core objects
Payment Receiving
Invoices
Billing
Collections
Payouts
Webhooks & events
SDKs & examples
Administration & security
Changelog & roadmap

MCP Server

Beta

The Orvion MCP (Model Context Protocol) server enables AI agents like Claude, GPT-4, and other LLMs to interact with your invoice system through natural language. The server exposes invoice operations as LLM-friendly tools that communicate with your FastAPI backend.

What is MCP?

Model Context Protocol (MCP) is a standard protocol for connecting AI assistants to external data sources and tools. The Orvion MCP server provides invoice management capabilities to AI agents.

Installation

Prerequisites

  • Python 3.10+
  • Running Orvion FastAPI backend
  • Valid API key from Orvion dashboard

Install Package

cd mcp-server
pip install -e .

Or install dependencies directly:

pip install mcp httpx pydantic pydantic-settings python-dotenv structlog

Configuration

Create a .env file in the mcp-server/ directory:

Environment Variables

| Variable | Required | Description | Example | |----------|----------|-------------|---------| | AGENTPAY_API_BASE_URL | Yes | Base URL of FastAPI backend | http://localhost:8000/v1 | | AGENTPAY_API_KEY | Yes | API key for authentication | test_xxx... | | AGENTPAY_ORG_ID | No | Organization ID (usually inferred from API key) | org_01HABC... | | AGENTPAY_TIMEOUT_SEC | No | HTTP timeout in seconds | 10 |

Running the Server

The MCP server uses stdio transport for communication with MCP clients:

python -m orvion_mcp.server

Available Tools

create_invoice

Create a new invoice for a customer.

Required fields:

  • customer_name: Customer name
  • amount: Invoice amount (must be positive)
  • currency: Currency code (e.g., EUR, USD, SAT)

Optional fields:

  • customer_email: Customer email address
  • customer_wallet: Wallet address or payment identifier
  • issued_at: ISO 8601 timestamp (default: now)
  • due_at: ISO 8601 timestamp
  • external_id: External reference ID for idempotency
  • status: Initial status - "draft" or "sent" (default: "sent")

Example:

get_invoice

Fetch a single invoice by ID.

Required fields:

  • id: Invoice ID

Example:

list_invoices

List invoices, optionally filtered by status or customer.

Optional fields:

  • status: Filter by status - "draft", "sent", "paid", "overdue", "canceled"
  • customer_email: Filter by customer email
  • limit: Maximum number of invoices (1-100, default: 20)

Example:

mark_invoice_paid

Mark an invoice as paid.

Required fields:

  • id: Invoice ID

Optional fields:

  • paid_at: ISO 8601 timestamp (default: now)
  • amount_paid: Amount paid (defaults to invoice amount)
  • payment_reference: Payment reference or transaction hash

Example:

Response Format

All tools return a consistent response format:

Success:

Error:

Error Codes

  • NOT_FOUND: Invoice doesn't exist
  • UNAUTHORIZED: Invalid or missing API key
  • VALIDATION_ERROR: Invalid input data
  • RATE_LIMITED: Rate limit exceeded
  • INVALID_STATUS: Invoice status doesn't allow this operation
  • CLIENT_ERROR: HTTP client error
  • INTERNAL_ERROR: Unexpected server error

Idempotency

Use external_id when creating invoices to achieve idempotency. If an invoice with the same external_id already exists, it will be updated instead of creating a duplicate.

Example:

Integration with Claude Desktop

Add to claude_desktop_config.json:

Rate Limiting

Rate limit errors from the Orvion API are propagated with error.code = "RATE_LIMITED". The MCP server doesn't implement its own rate limiting.

Observability

The MCP server logs:

  • Tool invocations (name, success/failure)
  • HTTP status codes from backend
  • Error codes

Never logged:

  • API keys
  • Sensitive customer data
  • Full request/response bodies

Related Documentation