Tool documentation

For reviewers and developers integrating Duesback's MCP server. User-facing setup is on the setup page; data handling on the security page.

Endpoint and sign-in

MCP (Streamable HTTP): https://duesback.com/mcp. REST mirror: OpenAPI. Agent instructions: llms.txt.

OAuth 2.1 with PKCE (S256 required), dynamic client registration, client-ID metadata documents, and a device authorization grant for clients without a browser callback. Metadata at /.well-known/oauth-authorization-server. Access tokens last 1 hour (30 days for device-flow clients); refresh tokens rotate and a replayed one revokes the family.

Scopes. duesback grants every tool. duesback.read is read-only: audits, findings, quotes and status, but no fees, disputes, autopay or disconnect. The consent page lets the user choose read-only regardless of what the client requested. API keys (Bearer dk_live_…) carry the full scope.

Self-registered clients. Registration is open, as the MCP specification recommends, and rate-limited. On the consent page the user sees where access will be sent. Destinations we vouch for (Meta's directory callback, loopback addresses, the device flow) get the normal page; any other destination is labelled an unverified app, the host is shown, and the read-only option starts selected. Clients that never obtain a token are deleted after 7 days.

Classification and approvals

Tools are classified as Read, Write or Sensitive write following Muse's scheme. Nothing here contacts a third party or moves money; the sensitive writes are the ones with financial or irreversible consequences for the user, and the host should ask for approval on every use.

Tool	Class	In read-only scope	What it does	Side effects	Errors
`audit_bills`	Write	yes	Analyzes 12 months of transactions and returns findings with actions, a first win, and verification of earlier outcomes.	Stores recurring-charge signatures and findings for this account (never raw transactions). May confirm, reverse or bill outcomes reported earlier when the data proves them. No external action.	invalid transactions (schema); more than 5,000 rows; audits paused while an installment is more than 7 days overdue (the response says so and lists the links).
`get_findings`	Read	yes	Open findings from the latest audit.	None.	None beyond authentication.
`get_playbook`	Read	yes	Provider notes for one finding.	None.	unknown finding_id.
`quote_fee`	Read	yes	The exact fee a report would create, with installments and terms.	None.	unknown finding_id; numbers that yield no fee return fee: null with an explanation.
`get_due_fees`	Read	yes	Unpaid installments with their Stripe Checkout links.	May create a fresh Checkout link for an installment whose link expired.	None beyond authentication.
`account_status`	Read	yes	Membership, open findings, outcomes, fees due and paid.	None.	None beyond authentication.
`report_outcome`	Sensitive write	no	Records what happened after acting on a finding. With evidence and the numbers, creates the success fee.	Creates fee installments (status due) and emails the user. Idempotent per finding: a repeated report returns the existing outcome and creates nothing. Payment still requires the user to approve each Checkout link.	unknown finding_id; missing numbers or evidence leave the report pending (no fee) and say what is missing.
`verify_outcome`	Write	no	Checks one reported outcome against fresh transactions now.	Confirms, reverses (cancels unpaid installments, refunds paid ones) or bills a pending outcome. Idempotent.	unknown outcome_id; invalid transactions.
`dispute_fee`	Write	no	Puts every unpaid installment of an outcome on hold and alerts a person.	Expires open payment links for that outcome. Nothing is collected while on hold.	unknown charge_id; reason shorter than 5 characters.
`enable_autopay`	Sensitive write	no	Returns a Stripe page where the user saves a card.	After the user completes it, fees are charged automatically 48 hours after creation unless disputed. Reversible with disable_autopay.	payments not configured.
`disable_autopay`	Write	no	Removes the saved card.	Future fees return to approve-per-link.	None.
`disconnect`	Sensitive write	no	Revokes all credentials and deletes stored signatures, findings and outcomes.	Irreversible for stored data. Fee records are kept for accounting and billed fees remain due.	None.

Fees: quote, commit, status

quote_fee returns the exact fee, the installments, the ${'48'}-hour objection window and the refund guarantee before anything is created. report_outcome creates the fee only with evidence and the numbers, is idempotent per finding, and the user still approves each payment on Stripe's Checkout page. Fee statuses: due, on_hold (disputed), succeeded (paid), cancelled (reversed before payment), refunded (reversed after payment). Outcome statuses: pending, billed, confirmed, reversed, disputed, charged. Receipts and notices go by email; disputes go through dispute_fee or hello@duesback.com.

Errors and limits

MCP tools return isError: true with a plain-language message; REST returns 400 (bad input), 401 (missing or expired credential, with WWW-Authenticate pointing at the resource metadata), 403 (inactive account or read-only scope), 404, 429.
Audits accept up to 5,000 transactions per call. Merchant classification has a 20-second model timeout and falls back to heuristics.
Sign-in and registration endpoints are rate-limited per address and per email (HTTP 429). Tool calls are not rate-limited beyond authentication.
Reported outcomes without evidence stay pending and are billed only when the next audit's data verifies them.

Testing

A reviewer account and a public demo dataset (https://duesback.com/demo/transactions.json, 9 findings) are provided in the submission. Payments made from the reviewer account are refunded automatically, so the full fee flow can be exercised without a real charge.

Contacts

Support and security: hello@duesback.com. Vulnerability disclosure: security.txt.