> 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/mcp-servers/overview.md).

# Overview

Modern Collections ships an **MCP (Model Context Protocol) stdio server** named `mc-api-mcp`. It lets an MCP-aware agent place invoices, track them, record payments, handle disputes, and read analytics/audit — all scoped to a single creditor by its API key.

There is no *hosted* MCP server at a public URL. `mc-api-mcp` is a local stdio process you run alongside your MCP client (Claude Code, Claude Desktop, etc.); it speaks to the Modern Collections REST API over HTTPS on your behalf.

## What it is

`mc-api-mcp` is one of the console scripts in the **`mc_api` Python package** (distributed by Modern Collections during onboarding). The package provides three front-ends over a single hardened HTTP client:

* a typed client — `mc_api.client.MCClient`
* a CLI — `mc-api`
* an **MCP stdio server** — `mc-api-mcp`

The server registers as the MCP server `modern-collections` and exposes the creditor-API-key endpoints as tools. The API key lives only in the request `Authorization` header — it is **never logged or printed**, and tool errors carry only the API's opaque `detail` and HTTP status, never the key.

## Tools

The server exposes these **8 tools** (snake\_case):

| Tool                  | Purpose                                                                                                                                                                                              |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `placement_create`    | Place an overdue commercial invoice for collection. `invoice_amount` is a positive decimal string (e.g. `"7500.00"`); `company_name` is the debtor company. Returns the new placement id and status. |
| `placement_status`    | Retrieve a placement (status, debtor, amounts, outreach state) by id.                                                                                                                                |
| `placement_list`      | List placements, paginated (`page`, `page_size`); optional comma-separated `status` filter.                                                                                                          |
| `payment_record`      | Record a payment received against a placement. `amount` is a positive decimal string.                                                                                                                |
| `dispute_get`         | Inspect the dispute (if any) filed by the debtor on a placement.                                                                                                                                     |
| `dispute_acknowledge` | Acknowledge a dispute filed by a debtor, optionally attaching a `note`.                                                                                                                              |
| `audit_query`         | Read a placement's append-only audit trail (keyset-paginated; optional `event_type`, `cursor`, `limit`).                                                                                             |
| `analytics_summary`   | Return headline per-creditor analytics (recovered totals, status counts, rates).                                                                                                                     |

## How to run it

The server runs over **stdio** and takes no command-line arguments — configuration comes entirely from the environment (so keys stay out of any MCP client config that might be logged):

```bash
MC_API_ENV=prod MC_API_KEY=ca_... mc-api-mcp
```

Your MCP client launches this process for you once it's registered (see below); you rarely run it by hand except to smoke-test.

## Configuration (environment variables)

| Var               | Values                                          |
| ----------------- | ----------------------------------------------- |
| `MC_API_ENV`      | `demo` \| `prod`                                |
| `MC_API_BASE_URL` | explicit base URL (overrides `MC_API_ENV`)      |
| `MC_API_KEY`      | creditor API key, format `ca_<prefix>_<secret>` |

Provide **either** `MC_API_ENV` **or** `MC_API_BASE_URL`, plus `MC_API_KEY`. There is **no production default** — by design you must choose an environment explicitly. Routes are versioned under `/v1`.

Environment → base URL map:

| env    | base URL                                |
| ------ | --------------------------------------- |
| `demo` | `https://app.demo.moderncollections.io` |
| `prod` | `https://api.moderncollections.io`      |

On `demo`, authenticated `/v1/*` calls reach the API normally. (The bare `/health` on that host is the dashboard origin, not the API.)

The same `Authorization: Bearer ca_<prefix>_<secret>` header authenticates every external route. See [Authentication](/getting-started/authentication.md) for how to obtain a creditor key.

## Register it with an MCP client

The server's id is `modern-collections` and the command is `mc-api-mcp`. Configuration shape (matching `mcp.example.json` shipped with the package):

```json
{
  "mcpServers": {
    "modern-collections": {
      "command": "mc-api-mcp",
      "env": {
        "MC_API_ENV": "prod",
        "MC_API_KEY": "ca_REPLACE_WITH_YOUR_CREDITOR_KEY"
      }
    }
  }
}
```

The API key is read from the server's environment and never appears in logs.

### Claude Code

```bash
claude mcp add modern-collections -- mc-api-mcp
# then set MC_API_ENV / MC_API_KEY in the server's environment
```

## See also

* [REST API overview](/rest-api/overview.md)
* [OpenAPI contract](https://github.com/knollmeyersam-dot/MC-Docs/blob/main/api-reference/rest-api/openapi.yaml) — the canonical, field-accurate machine-readable reference (generated from the live application)
* [Authentication](/getting-started/authentication.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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.moderncollections.io/mcp-servers/overview.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.