> For the complete documentation index, see [llms.txt](https://docs.moderncollections.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.moderncollections.io/clients/mcp.md). # MCP Connect an AI assistant to Modern Collections and upload invoices, contracts, and supporting evidence. An assistant (Claude, ChatGPT, Cursor, anything that speaks MCP) connects to the hosted MCP server. No local install is required. ``` URL: https://api.moderncollections.io/mcp Transport: streamable-http Auth: sign in (OAuth), or Authorization: Bearer ``` The URL and setup snippets are in the dashboard under **Settings → Developer & integrations**, at [llms.txt](https://moderncollections.io/llms.txt) and at `GET https://api.moderncollections.io/v1/public/mcp`. A request with no credential gets `401` with a `WWW-Authenticate` header that points the app at sign-in. The PyPI project `mc-api` is unrelated. ## Connect ### Sign in: Claude.ai, Claude Desktop, ChatGPT No API key is needed. 1. ChatGPT: connect Modern Collections from the plugin directory (availability depends on plan, region and workspace), or add `https://api.moderncollections.io/mcp` as a custom MCP server in a Business or Enterprise workspace. Claude: **Settings → Connectors → Add custom connector**, named "Modern Collections", with the same URL. 2. Choose **Connect** and sign in with your dashboard login. 3. Check which app is asking, which account it acts for and what it may do, then **Allow**. | Permission | Covers | | ------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | View your account | Placements, payments, disputes, documents and reports | | Make changes | Uploading and processing documents, acknowledging disputes, exports, settings | | Start, stop or change debtor outreach | Placing and recalling invoices, posture, debtor details and contacts, recording payments, resolving disputes | The last permission is off unless you tick it, because placing an invoice contacts the debtor. Without it a placing tool is refused until you reconnect and tick it. * A partner user connects the partner once and names a linked creditor on each call with `creditor` (name, id or external reference). The connection reaches what the full API key reaches, within the granted permissions and the person's role; a viewer only reads. * A Modern Collections staff login cannot connect apps. * Disconnect under **Settings → Developer & integrations → Connected apps → Revoke**. Revoking does not change your API key; rotating the key does not disconnect apps. * Whatever an app was granted, these stay in the dashboard: accepting the MSA, rotating the API key, the payout destination, settlement bounds, the webhook URL, the notification email. ### API key Create the key in the dashboard under **Settings → Developer & integrations**. It is shown once. Send it as `Authorization: Bearer `, plus `X-MC-Creditor` for a partner key. #### One command: Claude Code, Cursor, Claude Desktop ```bash uv tool install modern-collections # or: pip install modern-collections modern-collections mcp install --client claude-code # or cursor, claude-desktop ``` It asks for your key without echoing it, checks it, then writes the client's configuration. #### Any other client Add the hosted server to the MCP client's configuration: ```json { "mcpServers": { "modern-collections": { "url": "https://api.moderncollections.io/mcp", "headers": { "Authorization": "Bearer ca_REPLACE_WITH_YOUR_KEY" } } } } ``` ### Check the setup Reconnect the client, then ask the assistant to run `account_whoami`. It names the account, says whether it signed in or uses a key, and lists anything that blocks placing: verification, the MSA (accepted by a person in the dashboard), or the payout account. If something blocks, `getting_started` lists the setup steps in order. The assistant can save company details with `account_setup_update` until verification starts; the rest is finished in the dashboard. You can connect before the account is verified. For a partner key, `account_whoami` lists the linked creditors; pass one as `creditor=` on each call. The partner tools act across the book and take no `creditor`: | Tool | Does | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | | `partner_profile`, `partner_summary`, `partner_analytics`, `partner_top_debtors` | Your profile; the book's totals, analytics and largest debtors | | `partner_creditor_list` | Linked creditors | | `partner_placement_list`, `partner_export` | Placements across the book; a CSV of placements, remittances, payments, documents or the audit trail | | `partner_remittance_list`, `partner_statement_list`, `partner_statement_lines` | Every creditor's remittances and statements with totals; a statement's rows | | `partner_settlement_review_list`, `partner_intake_draft_list`, `partner_evidence_request_list`, `partner_audit` | Settlements waiting on you, invoices waiting for review, open document asks, your audit trail | | `partner_notification_settings_get`, `partner_notification_settings_replace` | What you and your creditors hear, per event | | `partner_creditor_import`, `partner_creditor_import_status`, `partner_creditor_import_list`, `partner_placement_import`, `partner_placement_import_status`, `partner_placement_import_list` | Bulk imports | | `partner_creditor_create`, `partner_creditor_update`, `partner_creditor_kyb_submit`, `partner_creditor_invite`, `partner_creditor_link_update`, `partner_creditor_recall_all`, `partner_evidence_request_fulfil`, `partner_webhook_events` | Onboarding and operations | Setting the partner webhook URL and the read-only key are not tools. ## What the assistant sees A default set of 32 tools covers placing, finding and following accounts, payments, disputes, documents, document asks and reporting. The full set of 140 (settlement floors, contact choices, pausing and undoing a recall, CSV and file intake, evidence scoring, the recovery workspace, notifications, webhooks, QuickBooks, partner tools) needs `?tools=all` on the URL or `X-MC-Tools: all`. A partner key sees the partner tools without opting in. The assistant finds accounts by name: `placement_list(q="Acme")` searches by debtor company or invoice number. `placement_list(updated_since="2026-10-01T12:00:00Z")` returns what changed after that instant, oldest change first; see [Catching up after a missed webhook](/webhooks/receiving.md#catching-up-after-a-missed-webhook). ## Confirmations Tools that contact a debtor, move money, change who is contacted or make a legal statement are marked destructive. There are 29: `placement_create`, `placement_amend`, `placement_recall`, `placement_pause`, `placement_resume`, `placement_unrecall`, `placement_update_debtor`, `placement_set_contacts`, `placement_remove_contact`, `placement_set_settlement_floor`, `settlement_policy_set`, `settlement_policy_clear`, `payment_record`, `dispute_resolve`, `document_share_with_debtor`, `intake_csv_commit`, `intake_file_confirm`, `intake_draft_resolve`, `intake_identity_review_resolve`, `intake_address_update`, `intake_address_delete`, `account_setup_update`, `notification_settings_replace`, `qbo_disconnect`, `partner_placement_import`, `partner_creditor_recall_all`, `partner_creditor_invite`, `partner_creditor_link_update`, `partner_notification_settings_replace`. The assistant asks before using them, and most MCP clients ask you too. To skip the ask, say so or choose "always allow" in your client. ## Upload an invoice Confirm the debtor company and the amount first: `placement_create` starts real outreach. Test on the [sandbox](/getting-started/quickstart.md#2-point-at-the-right-host). Commercial invoices only. Amounts are decimal strings, not floats. 1. `placement_create`: `company_name`, `invoice_amount` such as `"7500.00"`, `invoice_number`, `invoice_date`, `due_date`, and the AP email and phone and the debtor's state when known. 2. Attach the invoice: * If the assistant has the file, `document_upload` with `placement_id`, the file as `content_base64`, `filename`, and `document_type="invoice"`. * If the file is on your computer and the assistant cannot read it, `document_upload_link(placement_id=..., document_type="invoice")` returns a link. Open it in a browser and choose the file. It works for 30 minutes and needs no login, so do not share it. 3. `placement_context` reads back what was extracted, once the document is processed. 4. `placement_recall` stops outreach if the placement was a mistake. ``` document_upload( content_base64="BASE64_ENCODED_FILE_BYTES", filename="invoice.pdf", content_type="application/pdf", placement_id="PLACEMENT_ID", document_type="invoice" ) ``` `document_status` shows processing progress; `placement_documents` lists a placement's documents. Formats and limits are in [Upload files](/rest-api/documents.md). The hosted server refuses `file_path`; it cannot see your disk. ## Not available to an assistant Accepting the master service agreement, rotating the API key, and setting the webhook URL or the events it receives are done by a person in the dashboard. The intake webhook secret is kept out of the model. For terminal commands, see [CLI](/clients/cli.md). For direct HTTP, see [REST quickstart](/getting-started/quickstart.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.moderncollections.io/clients/mcp.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.