Cleared

npx add-mcp 'https://api.clearedpay.xyz/mcp'

MCP integration

Connect your AI assistant to Cleared to look up invoices, track payments, and manage customers. Use the hosted server with OAuth: sign in through your browser, choose an organization and network, and approve the permissions you want to grant. No repository access, local server, or API key is needed for this connection.

Connect the hosted server (recommended)

Setting	Value
Server URL	https://api.clearedpay.xyz/mcp
Transport	Streamable HTTP
Authentication	OAuth (browser sign-in)

1. Finish organization setup. Use a client that supports remote MCP with OAuth.
2. Add Cleared as a custom remote connector using the server URL above. Choose OAuth if the client asks for an authentication method.
3. Follow the client's connect/sign-in action. In the Cleared browser page, sign in and review the organization and network. A sole eligible choice may already be selected; approval is still yours.
4. Start with read access and leave write permissions unchecked. Review the permissions and approve, then return to your client.
5. Ask: “Show my five most recent Cleared invoices.” This calls list_invoices with { "limit": 5 } without creating anything. The hosted-only get_connection_profile with {} also provides a read-only connection check.

Each connection is bound to one organization and network. To use another, create a new connection and select it during consent. If no eligible organization appears, check that you signed into the correct Cleared account and have membership in that organization; contact support if an existing organization is missing.

Claude

In Claude web, open Settings → Customize and add a custom connector. Enter the hosted server URL, connect, and complete Cleared's browser consent. Enable the connector in your conversation and approve tool use when Claude asks. Custom-connector availability depends on your plan and workspace settings.

ChatGPT

In ChatGPT web, open Plugins → Add custom MCP server, enter the hosted server URL, and connect with OAuth. Complete Cleared's browser consent, then select the connected tool in your conversation. The custom MCP option must be available and enabled for your account/workspace.

These are the web setup surfaces verified with Cleared; client labels and availability can change. In other clients, use their remote MCP / Streamable HTTP setup and OAuth sign-in flow with the same URL. A local-stdio-only client cannot connect directly to this endpoint.

Permissions and writes

Hosted OAuth enforces the approved permissions on each call: invoice:read, customer:read, and dashboard:read for reads; invoice:write and customer:write for the corresponding mutations. Write permissions are never preselected. You can explicitly approve them on the first connection or reconnect to upgrade an existing connection. Viewer members can grant read access only.

For invoice writes, consent also sets a maximum amount per invoice, an invoice count, and a total amount per rolling 24 hours. Defaults are 1,000 USDC per invoice, 10 invoices, and 5,000 USDC per 24 hours; review and adjust them before approving. A fixed limit also allows at most 3 invoices to the same customer per 24 hours per connection. These are per-connection allowances, not organization-wide budgets. See limits and retry behavior.

Creating or canceling invoices additionally requires an active, unexpired server signer for that organization and network. OAuth consent does not activate it. The owner sets up write access in Settings → API Keys; if activation is pending, choose Finish activation and sign the activation. See write-access setup. Issuance also needs a completed business profile, deployed Safe, and complete customer billing details. Customer-only writes do not require an invoice signer.

send_invoice creates an invoice; email delivery is opt-in. cancel_invoice cancels an unpaid invoice. No MCP tool pays invoices, withdraws funds, or gives the assistant owner-wallet authority.

Manage or revoke a connection

Open Cleared Settings and find Your connections (or Organization connections for owners/admins). Review the scopes, network, invoice limits, and recent usage. Choose Revoke, then Confirm revoke to stop that connection immediately. Members can revoke their own connections; owners/admins can manage the organization's connections.

To change limits or add permissions, reconnect from the client and choose Upgrade an existing connection during consent. If the client only requests read scopes, it must request the write scopes before you can approve them. Removing a connector in a client is not a substitute for revoking it in Cleared.

Advanced alternative: local stdio with an API key

For integrations that need a local process, the MCP package is available from the private Cleared repository, not the public npm registry. Contact the team for repository access. This alternative uses HMAC API credentials instead of hosted OAuth.

1. Obtain repository access, install Bun, and run bun install from the checkout root.
2. Finish organization setup and create API credentials. Save both the clr_pk_ key ID and clr_sk_ secret.
3. For invoice writes, activate the server signer through owner settings. Prepare complete customers in the dashboard or REST API.
4. Add a local MCP configuration. Use your client's secret storage if available; protect any configuration file containing credentials.

{
  "mcpServers": {
    "cleared": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/cleared/packages/mcp/src/bin/cleared-mcp.ts"],
      "env": {
        "CLEARED_API_KEY": "clr_sk_REPLACE_WITH_YOUR_SECRET",
        "CLEARED_KEY_ID": "clr_pk_REPLACE_WITH_YOUR_KEY_ID",
        "CLEARED_API_URL": "https://api.clearedpay.xyz",
        "CLEARED_CHAIN": "base-sepolia"
      }
    }
  }
}

Replace the checkout path and placeholders. The source-entry command avoids requiring prebuilt MCP output. Ensure the MCP client can find Bun, or supply its absolute executable path. Do not paste secrets into an agent prompt.

CLEARED_API_URL defaults to https://api.clearedpay.xyz; CLEARED_CHAIN accepts base (default) or base-sepolia. Equivalent flags are --api-key=..., --key-id=..., --api-url=..., and --chain=...; flags override environment values. Prefer secret-managed environment values over command-line secrets.

The chain option does not override the studio's API network. Use a Base Sepolia organization and its credentials for the example. The MCP setting affects presentation such as network labels/explorer URLs, while authenticated API calls derive chain context from the studio. Match both settings to avoid misleading labels.

First local read

Invoke list_invoices with { "limit": 5 } or get_dashboard with {}. Read tools do not create invoices. Inspect errors and known limitations before relying on summary totals.

The server signs HTTP requests using HMAC; it does not turn the API key into an owner wallet. send_invoice creates an invoice, and cancel_invoice performs an on-chain cancellation. Neither tool pays an invoice or withdraws funds. Email is opt-in on send_invoice.

Tool coverage and limits

See all tool parameters. Invoice tools accept numeric global IDs or formatted merchant invoice numbers, resolved within your studio and issuance year. list_invoices accepts up to 50 results per page and returns page.next_cursor for continued traversal with the same filters. Invalid limits and dates are rejected.

create_customer and update_customer support billing addresses and entity registration data. Provide a name, email, complete address, and, for entities, registration_number. See the tool reference for creation examples and invoice retry behavior.

Legacy HMAC caveat: granular scope enforcement is incomplete on some legacy REST routes. A read-labeled API key is not an API-wide sandbox; give local stdio credentials only to trusted integrations. This caveat does not apply to the hosted OAuth permission boundary. See agents for API-key agent management.