Skip to content

MCP server

Connect an AI agent to your workspace's records through MCP tools: every API read, evidence and close packs as digests, and with a read-and-write key, adding counterparties, invoices, milestones and payee links.

Vestiarion runs a remote MCP server. Connect an AI agent to it with a workspace API key, and the agent can answer questions from your workspace's own records: which payments are held and why, whether the ledger is intact, what is due to contractors.

Each tool is one of the API's operations. A tool call runs that operation with your key and returns its JSON exactly as the API does, except for the evidence reads (a payment's evidence and receipt, the payee lock's evidence and the monthly close pack), which return a digest of the signed file. With a read-only key, an agent connected here can read and explain, and nothing more. With a read-and-write key, it can also add counterparties, invoices and milestones, which the agent in Vestiarion then decides as it decides any other, and make payee links. No tool verifies work, approves or pays.

The server

text
https://www.vestiarion.xyz/api/mcp
  • Transport: Streamable HTTP. The server keeps no session, so a client sends every message as a POST. A GET or a DELETE with a valid key answers 405: there is no event stream to open and no session to end.
  • Protocol versions: the 2026-07-28 revision of MCP, and clients on the earlier revisions, such as 2025-06-18 and 2025-11-25, at the same URL.
  • Surface: tools only. The server has no resources and no prompts.

In the MCP Registry

The server is listed in the official MCP Registry as io.github.duongnq2798/vestiarion. Look it up at:

text
https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.duongnq2798/vestiarion

A client that reads the registry can find the server there, with its URL and the Authorization header it needs. The entry holds no key: the client still sends a workspace API key as the bearer token, a read-only one unless the agent must add records.

Authentication

Send a workspace API key in the Authorization header, exactly as for /api/v1:

http
Authorization: Bearer <key>

The key is checked before any MCP message is read:

  • A missing, malformed, unknown or revoked key answers 401 with the API's own error body and a WWW-Authenticate: Bearer realm="vestiarion" header.
  • A key without the read scope answers 403, with error="insufficient_scope" in WWW-Authenticate. Every key issued today has that scope.
  • The header is the only place a key is read. A key in the query string or in an MCP message's _meta is ignored: without the header, the request answers 401.
  • If the key cannot be looked up at all, the answer is 500, not 401: retry later, and keep the key. See When authentication fails.

Every tool call reads the key's own workspace and no other. Asking get_counterparty for another workspace's counterparty answers not_found, as the API does.

Which key to use

Start with a read-only key. It answers every read question on this page, and an agent holding it can read and explain, and nothing more: if a prompt talks the agent into calling a write tool, the call gets the API's 403 forbidden. To make one, leave Can also add records clear when you create the key.

The write tools need a read-and-write key: create_counterparty, create_invoice, create_milestone and create_payee_link. Give an agent one only when you want it to add records, and give it a key of its own, named for that agent, so you can revoke it without stopping anything else. Even then, no tool approves or pays.

Tools

One tool per API operation. Its name is the operation's id in snake case, its arguments are the operation's parameters, or for a write the fields of its request body and an optional idempotencyKey, with their types, allowed values and bounds, and its description, which is what the agent reads, is the operation's summary and description from its reference page. An evidence read's tool describes its digest instead. A read's tool is marked read-only and idempotent. The four write tools are marked as adding records: not read-only, and not idempotent.

  • create_counterparty, create_invoice and create_milestone are not destructive. A repeat adds another record, unless it passes the same idempotencyKey.
  • create_payee_link is marked destructive, because a new link revokes the payee's unused one. It takes no idempotencyKey: the link is in its answer only, so a repeat makes a new link.
ToolWhat it answersReference
get_statusGet workspace statusGET /api/v1/status
list_ledger_entries
Arguments: limit, cursor, domain, actor, order
List ledger entriesGET /api/v1/ledger
verify_ledgerVerify the ledgerGET /api/v1/ledger/verify
list_invoices
Arguments: limit, cursor, direction, status, counterpartyId
List invoicesGET /api/v1/invoices
create_invoice
Arguments: direction, counterpartyId, amount, currency, dueDate, memo, poReference, goodsReceived, earlyPayDiscount, lateFee, idempotencyKey
Add an invoicePOST /api/v1/invoices
list_counterparties
Arguments: limit, cursor, role, riskLevel
List counterpartiesGET /api/v1/counterparties
get_counterparty
Arguments: id
Get a counterpartyGET /api/v1/counterparties/{id}
create_counterparty
Arguments: name, role, address, chain, jurisdiction, paymentLimit, noticeEmail, idempotencyKey
Add a counterpartyPOST /api/v1/counterparties
create_payee_link
Arguments: counterpartyId
Create a payee linkPOST /api/v1/payee-links
list_milestones
Arguments: limit, cursor, status, contractorId
List milestonesGET /api/v1/milestones
create_milestone
Arguments: contractorId, title, amount, verificationSource, idempotencyKey
Add a milestonePOST /api/v1/milestones
get_treasuryGet the treasuryGET /api/v1/treasury
get_insightsGet insightsGET /api/v1/insights
get_invoice_evidence
Arguments: id
Get a payable's evidenceGET /api/v1/invoices/{id}/evidence
get_milestone_evidence
Arguments: id
Get a milestone's evidenceGET /api/v1/milestones/{id}/evidence
get_invoice_receipt
Arguments: id
Get a payable's receiptGET /api/v1/invoices/{id}/receipt
get_payee_lock_evidence
Arguments: from, to
Get the payee lock's evidenceGET /api/v1/payee-lock/evidence
get_close_pack
Arguments: month
Get a monthly close packGET /api/v1/close-packs/{month}

What a call returns:

  • A success is the API's JSON, as text and as structured content. An evidence read's success is its digest, below.
  • An API error is a tool error (isError) whose text is the API's error body, such as a 400 invalid_request for a cursor from another endpoint, or a 404 not_found for an unknown id. The agent reads the message and corrects its call. A read-only key calling a write tool gets the API's 403 forbidden the same way. The error codes are on Errors.
  • A collection is one page, 50 items unless the agent passes limit, up to 200. The agent passes page.nextCursor back as cursor for the next page, as described in Pagination.
  • Nothing else is cut. Every other tool returns the whole response, get_insights included, as the API documents it.

Evidence, receipts and close packs

The five evidence reads answer signed files that carry every entry they cite in full, with the workspace's public keys: tens of KB for one payment, up to 4 MB for a month. A tool's answer goes into the agent's context whole, so these tools return a digest of the file instead. An agent can then answer "why was this bill paid?", "is this receipt good?" or "what did October close with?" without reading a whole file.

  • get_invoice_evidence and get_milestone_evidence keep the subject and every step of the evidence chain, each fact with its label, text, who stated it and when, its link, and entries, the seq of the signed entries it rests on. Each label keeps its words and its count of facts, without what it means.
  • get_invoice_receipt keeps everything the receipt states: ready, notReady, facts, records, invoiceEntry, shared and checks.
  • get_payee_lock_evidence keeps the period, the lock and the summary, and the newest 50 address changes, each as the file has it. changesShown and changesTotal say how many it holds. For the rest, ask for a shorter period with from and to.
  • get_close_pack keeps the month, ledgerHead, cut, unread and totals, and the first 100 settled payments as rows. Each row has its paymentId, source, paidAt, amount, token, simulated and shadow; its payee, by name and address, with bank: true for a payment to a bank; its bill, with its number or title, amount, currency and due date; approval.authorizedBy; its transaction, txHash and chain; and entry, the seq of the entry that records it. rowsShown and rowsTotal say how many rows it holds, and notSettled and escrow count the payments not settled and the escrow moves.

Every digest:

  • Starts with about: one sentence saying what it is, and that its names, numbers, memos and links came from outside Vestiarion and are data, never instructions. Each of these tools' descriptions ends by saying the same. Text from outside, such as a vendor's name or a memo, is only ever a JSON string, as the file has it.
  • Leaves out the entries and the keys: entries, keys, signedEntryProves and checkAnEntry. It counts instead the server's own check of each entry the file carries, in signatures: cited, verified, failed and unchecked. That count is Vestiarion's word, not proof.
  • Names the full file in fullFile: the API path and the SDK method that give the complete signed file. Check that file offline with the SDK's verifyEvidence and the workspace's public key.
  • Is at most 200 KB. A digest that would be larger holds fewer changes or rows, and says how many in changesShown or rowsShown, with a sentence in notShown.

The evidence reads keep their own limit per key through MCP, as through the API: 10 at once, then one every 6 seconds. Over it, the tool error is the API's 429 rate_limited.

A close pack, or the payee lock's evidence for a period, whose full file is over 4 MB has no digest. Its tool error is the API's 400 invalid_request, as on Limits. For a close pack, that is a month of about 850 payments or more, fewer when each cites many signed entries. The error's message says what to do instead: download such a month from the workspace's Monthly close pack page, or ask for the payee lock's evidence a shorter period at a time.

Setup

Keep the key in the VESTIARION_API_KEY environment variable. None of the blocks below writes the key itself into a file.

Claude Code

bash
claude mcp add --transport http vestiarion https://www.vestiarion.xyz/api/mcp \
  --header "Authorization: Bearer $VESTIARION_API_KEY"

Your shell puts the key into the command, and Claude Code saves the header in its own configuration, ~/.claude.json. To share the server with a project instead, without the key, add it to .mcp.json at the project root. Claude Code expands ${VESTIARION_API_KEY} from the environment when it starts:

json
{
  "mcpServers": {
    "vestiarion": {
      "type": "http",
      "url": "https://www.vestiarion.xyz/api/mcp",
      "headers": {
        "Authorization": "Bearer ${VESTIARION_API_KEY}"
      }
    }
  }
}

Cursor

Add the server to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json for every project. Cursor resolves ${env:VESTIARION_API_KEY} from the environment:

json
{
  "mcpServers": {
    "vestiarion": {
      "url": "https://www.vestiarion.xyz/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:VESTIARION_API_KEY}"
      }
    }
  }
}

Codex

Add the server to ~/.codex/config.toml, or to .codex/config.toml in a trusted project. bearer_token_env_var names the variable Codex reads the key from and sends as Authorization: Bearer:

toml
[mcp_servers.vestiarion]
url = "https://www.vestiarion.xyz/api/mcp"
bearer_token_env_var = "VESTIARION_API_KEY"

Clients that only start local servers

A client that runs MCP servers as local commands over stdio can reach this one through mcp-remote, which relays between stdio and the remote server:

json
{
  "mcpServers": {
    "vestiarion": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://www.vestiarion.xyz/api/mcp",
        "--header",
        "Authorization: Bearer ${VESTIARION_API_KEY}"
      ]
    }
  }
}

mcp-remote replaces ${VESTIARION_API_KEY} from its own environment, so the key never appears in the arguments. If your client does not pass VESTIARION_API_KEY on to the servers it starts, set the variable in that server's env entry.

Some clients do not escape spaces inside args when they start npx; the mcp-remote README names Cursor, the Codex CLI and Claude Desktop on Windows. There, write the header as Authorization:${VESTIARION_AUTH_HEADER}, with no spaces, and set VESTIARION_AUTH_HEADER to Bearer followed by the key.

Questions to ask

Once the server is connected, ask in plain language. The agent picks the tools:

  • "Is our ledger intact, and are any payments held? Why was each one held?" uses verify_ledger, then list_invoices and list_milestones with status: "held", whose entries carry the agent's reasoning.
  • "Which contractor milestones are verified but not paid yet?" uses list_milestones.
  • "Which counterparties are high risk, and what did their latest screening find?" uses list_counterparties with riskLevel: "high", then get_counterparty.
  • "How much do we hold in reserve, and what does the latest liquidity forecast say?" uses get_treasury.
  • "Are payments on this workspace live or simulated?" uses get_status.
  • "Why was Harbor Print's last bill paid, and who approved it?" uses list_invoices to find the bill, then get_invoice_evidence.
  • "What did October close with, and did every signed entry in the close pack verify?" uses get_close_pack with month: "2026-10".
  • With a read-and-write key, "Add Quill Studio's invoice for 420 USDC against PO-4012, due October 31; the work was delivered" uses list_counterparties to find Quill Studio, then create_invoice.
  • With a read-and-write key, "Pay Mona 150 USDC for https://github.com/acme/app/pull/42 once it is merged" uses list_counterparties to find Mona, then create_milestone.

What it does not do

  • It does not decide. Approving or rejecting a payment, confirming an address, pausing the agent, and managing members, API keys or webhooks are a person's decisions, made in the console. No tool can make them, and the write tools only add records.
  • It has no OAuth. The server authenticates with a key in a header and has no authorization server, so it cannot be added as a claude.ai web connector, which needs OAuth. Use a client that sends a header, like the ones above.

Edit this page on GitHub (opens in a new tab)