Connect your agent

Billr exposes a remote MCP server at https://mcp.billr.cc. In most clients that URL is the only thing you paste.

Signing in shows a consent screen that asks which business the agent may work in and which permissions it gets, with read and write on by default and send, payments and delete optional. Every connection shows up under Agents → API Keys and can be revoked there at any time.

Clients that cannot sign in still work with a billr_sk_ key sent as a bearer token. Each guide below carries that fallback under “Use an API key instead”.

For what the connection can do once it is set up, and which permissions let an agent send, read the MCP server overview.

Set up per agent

Claude

What you need: A Claude account on any plan. Free accounts can add one custom connector. On Team and Enterprise only an Owner can add the connector, after which each member connects for themselves.

  1. Open your connector list

    In claude.ai or Claude Desktop, go to Customize, then Connectors. Team and Enterprise Owners add it from Organization settings, then Connectors.

  2. Add a custom connector

    Click the plus button, then "Add custom connector". Team and Enterprise Owners click "Add", hover "Custom" and select "Web".

  3. Paste the Billr MCP URL

    The URL is the only field you need. Leave Advanced settings empty: Billr registers Claude as a client on its own, so there is no client ID or secret to paste.

    MCP SERVER URL
    https://mcp.billr.cc

  4. Click Add, then Connect

    Claude sends you to Billr to sign in and approve the connection. Pick the business and the permissions, then approve.

  5. Switch Billr on in a chat

    Use the plus button at the bottom of the chat, choose Connectors, and toggle Billr on for that conversation.

Then verify: Ask Claude: "List my Billr clients and tell me what is still unbilled." It reads only, so nothing is created or sent.

Checked against the vendor documentation on 2026-09-21. If their menus have moved since, follow their wording and keep the URL above.

Claude Code

What you need: Claude Code installed, and a terminal open in any project directory.

  1. Add the server

    Run this once. Add --scope user to make Billr available in every project instead of only this one.

    TERMINAL
    claude mcp add --transport http billr https://mcp.billr.cc

  2. Start Claude Code and run /mcp

    Pick billr from the list and choose to authenticate. Claude Code opens Billr in your browser.

    IN CLAUDE CODE
    /mcp

  3. Approve in the browser

    Sign in to Billr, choose the business and the permissions, and approve. Then go back to your terminal.

  4. Check it is connected

    billr should be listed as connected.

    TERMINAL
    claude mcp list

Then verify: Ask Claude Code: "List my Billr clients and tell me what is still unbilled." It reads only, so nothing is created or sent.

Use an API key instead

Create a key under Agents → API Keys, then pass it as a bearer token when you add the server. Replace YOUR_KEY with the key you copied.

  1. Add the server with a key

    TERMINAL
    claude mcp add --transport http billr https://mcp.billr.cc --header "Authorization: Bearer YOUR_KEY"

Checked against the vendor documentation on 2026-09-21. If their menus have moved since, follow their wording and keep the URL above.

Codex

What you need: The Codex CLI installed and signed in.

  1. Add the server

    TERMINAL
    codex mcp add billr --url https://mcp.billr.cc

  2. Sign in

    Codex opens Billr in your browser. Choose the business and the permissions, then approve.

    TERMINAL
    codex mcp login billr

  3. Check it is connected

    billr should appear in the list. Inside the Codex TUI, /mcp shows the same thing.

    TERMINAL
    codex mcp list

Then verify: Ask Codex: "List my Billr clients and tell me what is still unbilled." It reads only, so nothing is created or sent.

Use an API key instead

Create a key under Agents → API Keys and export it as BILLR_API_KEY in the shell that starts Codex, then add this table to ~/.codex/config.toml, or to .codex/config.toml for one project.

  1. Configure a bearer token

    ~/.codex/config.toml
    [mcp_servers.billr]
url = "https://mcp.billr.cc"
bearer_token_env_var = "BILLR_API_KEY"

Checked against the vendor documentation on 2026-09-21. If their menus have moved since, follow their wording and keep the URL above.

Cursor

What you need: Cursor, and a project folder if you want Billr only in that project.

  1. Create the config file

    Use .cursor/mcp.json in the project root for one project, or ~/.cursor/mcp.json for every project.

  2. Paste the server entry

    A url entry is all Cursor needs. Cursor registers itself with Billr automatically, so there is no client ID to fill in.

    .cursor/mcp.json
    {
  "mcpServers": {
    "billr": {
      "url": "https://mcp.billr.cc"
    }
  }
}

  3. Save the file and sign in

    Billr appears in the MCP list on the Customize page. Cursor supports OAuth for servers that require it, so it opens Billr in your browser. Choose the business and the permissions, then approve.

Then verify: Ask Cursor: "List my Billr clients and tell me what is still unbilled." It reads only, so nothing is created or sent.

Use an API key instead

Create a key under Agents → API Keys and set BILLR_API_KEY in the environment Cursor starts from, then send it as a header. Cursor reads ${env:NAME} in header values, so the key never sits in the file.

  1. Send the key as a header

    .cursor/mcp.json
    {
  "mcpServers": {
    "billr": {
      "url": "https://mcp.billr.cc",
      "headers": {
        "Authorization": "Bearer ${env:BILLR_API_KEY}"
      }
    }
  }
}

Checked against the vendor documentation on 2026-09-21. If their menus have moved since, follow their wording and keep the URL above.

ChatGPT

What you need: A ChatGPT account with developer mode available. OpenAI documents the steps below but does not list which plans include developer mode, so check your own Settings first.

  1. Turn on developer mode

    In ChatGPT, open Settings, then "Security and login", and turn on Developer mode.

  2. Open the plugin list

    Go to ChatGPT Plugins and select the plus button.

  3. Connect the Billr MCP URL

    Paste the URL and connect the server in developer mode.

    MCP SERVER URL
    https://mcp.billr.cc

  4. Sign in to Billr

    ChatGPT runs an OAuth flow against Billr. Choose the business and the permissions, then approve. There is no API key option here: OAuth is the only way in.

Then verify: Ask ChatGPT: "List my Billr clients and tell me what is still unbilled." It reads only, so nothing is created or sent.

Checked against the vendor documentation on 2026-09-21. If their menus have moved since, follow their wording and keep the URL above.

Other / API key

What you need: Any client that can talk to a remote MCP server over streamable HTTP.

  1. Add a remote HTTP MCP server with this URL

    If the client supports MCP authorization, that is everything it needs. It discovers the Billr sign-in page from the URL and asks you to approve a business and a set of permissions.

    MCP SERVER URL
    https://mcp.billr.cc

  2. Sign in when the client opens Billr

    Choose the business and the permissions, then approve. The connection then shows up under Agents → API Keys.

  3. If the client cannot sign in, use a key

    Clients with no OAuth support can still connect with a bearer token. Open the panel below.

Then verify: Ask your agent: "List my Billr clients and tell me what is still unbilled." It reads only, so nothing is created or sent.

Use an API key instead

Create a key under Agents → API Keys, copy it once, and give the client the URL plus an Authorization header. A wrong or revoked key gets a 401 rather than an empty list, so a bad key never looks like an empty account.

  1. URL and header

    MCP CONFIGURATION
    URL: https://mcp.billr.cc
Authorization: Bearer YOUR_KEY

Worked examples with real output: Draft an invoice from Claude Code and Draft an invoice from Codex.

All 53 tools at a glance

Every tool is business-scoped to the connection that calls it. Mutating tools return the entity plus a link your agent can hand back to you: the client-facing invoice or estimate URL, the PDF, and the page in your dashboard.

Task billing

Track active work and reported usage under human-approved pricing.

  • list_billing_policies
  • create_task
  • start_task
  • heartbeat_task
  • pause_task
  • complete_task
  • record_task_usage
  • get_task_billing_preview

Clients

Look up and maintain the client list.

  • list_clients
  • get_client
  • create_client
  • update_client

Invoices

Draft, edit, send, and settle invoices.

  • list_invoices
  • get_invoice
  • create_invoice
  • update_draft_invoice
  • send_invoice
  • record_payment

Estimates

Quote work up front, then turn an accepted quote into an invoice.

  • list_estimates
  • get_estimate
  • create_estimate
  • update_draft_estimate
  • send_estimate
  • convert_estimate_to_invoice

Engagements

Agreed totals billed off a schedule, with nothing sent automatically.

  • list_engagements
  • get_engagement
  • list_ready_to_bill
  • create_engagement
  • update_engagement
  • mark_milestone_complete
  • complete_engagement
  • waive_engagement_entry
  • convert_estimate_to_engagement

Saved items

The rate catalog invoices and estimates can bill from by name.

  • list_items
  • create_item
  • update_item

Time

Log and correct tracked time before it gets billed.

  • log_time
  • list_time_entries
  • update_time_entry
  • delete_time_entry

Expenses

Log and correct expenses, billable or not.

  • log_expense
  • list_expenses
  • update_expense
  • delete_expense

Payments

Check what has been paid, what is still due, and correct or void a payment that was recorded wrong.

  • get_payment_status
  • update_payment
  • void_payment

Business and links

Business settings, revenue rollups, and shareable links.

  • get_profile
  • get_business
  • list_businesses
  • revenue_summary
  • get_invoice_link
  • list_unbilled

The tool reference lists every tool with the permission it needs, so you know what you are granting on the consent screen.

Check that it worked

Ask your agent for something read-only first. If the connection is right, this comes back with your own data and nothing is written:

FIRST PROMPT
List my Billr clients and tell me what is still unbilled.

If the connection is missing or revoked, the server answers with a 401 rather than a silent empty list, so a revoked agent never looks like an empty account.

Where to go next

  • Find unbilled work: read the grouped list, fix flagged rates, and draft the invoice from the entries themselves.
  • Estimates and items: quote work up front, convert an accepted quote, and bill a saved rate by name.
  • Getting paid: connect Stripe, test your checkout, and read payment status from an agent.
  • Recipes: copy-paste patterns for a CLAUDE.md or AGENTS.md file.

The self-hosted application, including this MCP server and the agent toolkit, is public on GitHub under Apache-2.0. Source in the repository is not a marketplace listing in any client: connect with the steps above. See the hosting details for what runs where.

Open source