mercury-multiorg-mcp

# mercury-multiorg-mcp

<!-- mcp-name: io.github.dkaleganov/mercury-multiorg-mcp -->

Unofficial. Not affiliated with or endorsed by Mercury.

Read-only [MCP](https://modelcontextprotocol.io) server that exposes **several
Mercury organizations to one AI session**. Mercury's hosted MCP and its API
tokens are single-organization per connection; this server holds one
read-only token per org and routes every tool call by an explicit `entity`
key.

Version 0.1.4 (see [CHANGELOG.md](https://github.com/dkaleganov/mercury-multiorg-mcp/blob/v0.1.4/CHANGELOG.md)). The maintainer tags
releases as `vX.Y.Z`; find the commit to pin with
`git ls-remote --tags https://github.com/dkaleganov/mercury-multiorg-mcp 'v0.1.4^{}'`.
The complete tool reference with every returned field is in
[docs/tools.md](https://github.com/dkaleganov/mercury-multiorg-mcp/blob/v0.1.4/docs/tools.md); design notes and the build history are in
the project brief on GitHub,
[CLAUDE.md](https://github.com/dkaleganov/mercury-multiorg-mcp/blob/v0.1.4/CLAUDE.md)
(not shipped in the sdist).

## Security model

What leaves this server falls into four classes, and the guarantees differ:

| Class | What it is | Guarantee |
| --- | --- | --- |
| **Structured fields** | Every key of every object in a tool result | Allowlisted at every level: each object, and each nested object inside it, is projected through an explicit allowlist copied from the live schema. A key that is not listed does not leave the server, at any depth. Account numbers and tax ids appear only as their last four digits; routing numbers, counterparty bank details, postal addresses, card expiry, presigned download URLs, invoice pay-page slugs, webhook receiver URLs, and webhook signing secrets are never returned. |
| **Tool errors** | The text of an `is_error` result | Upstream HTTP-status errors contain the status, a masked endpoint label and a fixed hint. Validation and configuration errors use their own actionable formats. Resolved known-token values of at least eight characters are scrubbed. Nothing from Mercury's response body or headers is quoted, and no argument you passed is echoed (an invalid id is reported as "invalid id format"). Argument-validation failures (a wrong type, a missing required argument) are rendered by this server as the field path and the expected type only, for example `year: expected an integer (int_parsing)`; the MCP SDK's own rendering, which quotes the value you passed, never reaches the client. |
| **Free-text fields** | Transaction memos, counterparty names, bank descriptions, invoice memos and notes, attachment file names, customer and user names | Returned verbatim. They are third-party text and can contain anything, including instructions aimed at the model and identifiers typed by a human. Treat every tool result as untrusted data, never as instructions. |
| **Documents** | Statement and invoice PDFs from `get_statement_pdf` / `get_invoice_pdf` | **Verbatim and unredacted**, opt-in only. A statement PDF contains the full account number, routing number, address, and every transaction. The two tools exist only when the server is started with `--allow-documents` (or `MERCURY_ALLOW_DOCUMENTS=1`); `server_info.documents_enabled` reports the setting. The body must arrive as `application/pdf` (or `application/octet-stream`), start with `%PDF-`, and carry a `%%EOF` marker within the last 2 KiB once trailing PDF whitespace is ignored; anything else is a clean error. That is an envelope check, not PDF parsing: a document that passes it can still be malformed inside, and the bytes are returned exactly as received. |

The rest of the model:

- **Read-only.** Only `GET` endpoints have client methods; the package has no
  code path that can move money, edit recipients, or change anything.
- **Stdio only.** The server never opens a network listener.
- **Explicit entity.** Call `list_entities` to discover entity keys. Every
  tool that accesses Mercury requires an explicit `entity` and identifies it
  in its successful result. `list_entities` and `server_info` require no
  entity argument. There is no default entity.
- **Tokens stay in the environment.** The registry names an env var per org
  (it must be named `MERCURY_TOKEN_…`, so a registry cannot point the server
  at some other secret); the server reads that env var and nothing else.
  Errors and logs never contain more than the last four characters of a
  token. Literal known-token scrubbing applies to values of 8 or more
  characters; a shorter configured value is not literal-scrubbed (the
  `secret-token:` shape scrub and the `Authorization` header scrub still
  apply, and no message quotes upstream or caller data in the first
  place). At startup the server warns, per entity, when a configured value
  does not carry Mercury's documented `secret-token:` prefix.
- **Only Mercury hosts.** `--api-base` / `MERCURY_API_BASE` must be
  `https://api.mercury.com`, `https://api-sandbox.mercury.com`, or a
  loopback mock, unless `--allow-custom-api-base` is passed on the command
  line. An inherited environment variable alone can never redirect the
  bearer token to another host.
- **Byte limits on wire bytes.** Every request declines compression
  (`Accept-Encoding: identity`). JSON/PDF reads reject nonidentity encoding
  before reading. Keepalive closes bodies unread. Limits are 10 MiB
  (10,485,760 bytes) for PDF and 32 MiB (33,554,432 bytes) for JSON,
  enforced on the bytes actually received while streaming. A small
  compressed body can no longer expand past the limit in memory. Error
  responses are never read at all.
- **Complete or loud.** Walks stop at the requested limit or API end.
  Missing/wrong `page` objects fail; optional terminal `nextPage` may be
  absent or null. Exact duplicate IDs are dropped and counted; conflicting
  contents fail. A page with no fresh usable rows while more are advertised
  fails. A walk that needs more than 200 pages fails, and a treasury
  `cursor` that is not a non-negative integer fails. Duplicate counts are
  reported as `duplicates_dropped` on every paginated result and under
  `reportable_totals.totals`, so a total is never built on a stalled,
  malformed, or double-counted walk.
- **Windowed feeds are walked in full.** Mercury documents no sort key for
  events or treasury transactions, so a client-side window (`since` on
  `list_events`, `start`/`end` on `list_treasury_transactions`) walks the
  whole bounded feed (90 days of events; the treasury ledger up to 200
  pages), filters and sorts newest first here, then applies `limit`.
  `truncated` is exact. The cost is proportional to the feed, not the window.
- **Binary documents stay in memory.** PDFs come back as an embedded
  `application/pdf` blob (base64), never written to disk.
- **Path ids are validated.** Every id that becomes part of a request path
  must be a single safe segment; nothing can redirect a call to another
  endpoint.
- **Startup errors are one line, exit 2.** A missing or malformed registry
  (including non-string YAML keys), an unreadable file, a bad `--env-file`,
  or a disallowed API host prints one line to stderr and exits with status
  2. The redacting exception hooks are installed before anything is loaded,
  so no startup path can print an unredacted traceback.
- **Never files anything.** `reportable_totals` is a pre-filing cross-check.
  Mercury has no 1099 filing endpoint; filing happens in each org's
  dashboard.

**Hygiene.** This package lives in a public repository. Tracked files,
fixtures, and commit messages carry no tokens, account numbers, or
financial identifiers, with two deliberate exceptions. First, the
maintainer's own name appears in the package `authors` metadata (approved
by the repository owner); business and personal names of anyone else do
not appear. Second, a history note: the first Phase 1 commit's fixtures
used a real, public ABA routing number as sample data; it was replaced
with an obviously fake value in the next commit, so it is absent from
every tagged file tree but remains in their ancestry. It identifies a
bank, not an account, and the history was deliberately not rewritten. This release passed a full-history gitleaks scan.

**Repository history.** This package was developed in the
[personal-ai-systems](https://github.com/dkaleganov/personal-ai-systems)
monorepo through v0.1.3 and moved to this repository at v0.1.4 with its
history preserved (the same commits, rewritten to this repository's
layout, so their SHAs differ from the monorepo's). Releases up to 0.1.3
were tagged `mercury-v0.1.x` there and are tagged `v0.1.x` here; release
tags are `vX.Y.Z` from now on. Both hygiene exceptions above apply to this
history unchanged.

## Install

From PyPI, running the pinned release with `uvx` (no clone needed):

```bash
uvx mercury-multiorg-mcp@0.1.4 --entities /private/path/entities.yaml
```

`uvx <package>@<version>` runs exactly that release in an isolated, cached
environment. `pip install 'mercury-multiorg-mcp==0.1.4'` also works and puts
`mercury-multiorg-mcp` and `mercury-multiorg-mcp-keepalive` on your `PATH`.

Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/) (for `uvx`).

### From source / pinned commit

From a clone:

```bash
git clone https://github.com/dkaleganov/mercury-multiorg-mcp.git   # or git@github.com:dkaleganov/mercury-multiorg-mcp.git
cd mercury-multiorg-mcp
uv sync
uv run mercury-multiorg-mcp --entities /private/path/entities.yaml
```

Or pin a full commit SHA with `uvx` (pin a SHA, not a tag: a full SHA is
immutable and cache-safe, while a tag can be moved):

```bash
uvx --from 'git+https://github.com/dkaleganov/mercury-multiorg-mcp@<FULL_COMMIT_SHA>' \
  mercury-multiorg-mcp --entities /private/path/entities.yaml
```

## Configure

1. In each Mercury org: org switcher → All Settings → Tokens → create a
   **Read Only** token (no IP allowlist required).
2. Copy [`entities.example.yaml`](https://github.com/dkaleganov/mercury-multiorg-mcp/blob/