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
https://www.vestiarion.xyz/api/mcp- Transport: Streamable HTTP. The server keeps no session, so a client sends every message as a
POST. AGETor aDELETEwith a valid key answers405: 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:
https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.duongnq2798/vestiarionA 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:
Authorization: Bearer <key>The key is checked before any MCP message is read:
- A missing, malformed, unknown or revoked key answers
401with the API's own error body and aWWW-Authenticate: Bearer realm="vestiarion"header. - A key without the
readscope answers403, witherror="insufficient_scope"inWWW-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
_metais ignored: without the header, the request answers401. - If the key cannot be looked up at all, the answer is
500, not401: 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_invoiceandcreate_milestoneare not destructive. A repeat adds another record, unless it passes the sameidempotencyKey.create_payee_linkis marked destructive, because a new link revokes the payee's unused one. It takes noidempotencyKey: the link is in its answer only, so a repeat makes a new link.
| Tool | What it answers | Reference |
|---|---|---|
get_status | Get workspace status | GET /api/v1/status |
list_ledger_entriesArguments: limit, cursor, domain, actor, order | List ledger entries | GET /api/v1/ledger |
verify_ledger | Verify the ledger | GET /api/v1/ledger/verify |
list_invoicesArguments: limit, cursor, direction, status, counterpartyId | List invoices | GET /api/v1/invoices |
create_invoiceArguments: direction, counterpartyId, amount, currency, dueDate, memo, poReference, goodsReceived, earlyPayDiscount, lateFee, idempotencyKey | Add an invoice | POST /api/v1/invoices |
list_counterpartiesArguments: limit, cursor, role, riskLevel | List counterparties | GET /api/v1/counterparties |
get_counterpartyArguments: id | Get a counterparty | GET /api/v1/counterparties/{id} |
create_counterpartyArguments: name, role, address, chain, jurisdiction, paymentLimit, noticeEmail, idempotencyKey | Add a counterparty | POST /api/v1/counterparties |
create_payee_linkArguments: counterpartyId | Create a payee link | POST /api/v1/payee-links |
list_milestonesArguments: limit, cursor, status, contractorId | List milestones | GET /api/v1/milestones |
create_milestoneArguments: contractorId, title, amount, verificationSource, idempotencyKey | Add a milestone | POST /api/v1/milestones |
get_treasury | Get the treasury | GET /api/v1/treasury |
get_insights | Get insights | GET /api/v1/insights |
get_invoice_evidenceArguments: id | Get a payable's evidence | GET /api/v1/invoices/{id}/evidence |
get_milestone_evidenceArguments: id | Get a milestone's evidence | GET /api/v1/milestones/{id}/evidence |
get_invoice_receiptArguments: id | Get a payable's receipt | GET /api/v1/invoices/{id}/receipt |
get_payee_lock_evidenceArguments: from, to | Get the payee lock's evidence | GET /api/v1/payee-lock/evidence |
get_close_packArguments: month | Get a monthly close pack | GET /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 a400 invalid_requestfor a cursor from another endpoint, or a404 not_foundfor an unknown id. The agent reads the message and corrects its call. A read-only key calling a write tool gets the API's403 forbiddenthe 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 passespage.nextCursorback ascursorfor the next page, as described in Pagination. - Nothing else is cut. Every other tool returns the whole response,
get_insightsincluded, 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_evidenceandget_milestone_evidencekeep thesubjectand every step of the evidence chain, each fact with its label, text, who stated it and when, its link, andentries, theseqof the signed entries it rests on. Each label keeps its words and its count of facts, without what it means.get_invoice_receiptkeeps everything the receipt states:ready,notReady,facts,records,invoiceEntry,sharedandchecks.get_payee_lock_evidencekeeps theperiod, thelockand thesummary, and the newest 50 addresschanges, each as the file has it.changesShownandchangesTotalsay how many it holds. For the rest, ask for a shorter period withfromandto.get_close_packkeeps themonth,ledgerHead,cut,unreadandtotals, and the first 100 settled payments asrows. Each row has itspaymentId,source,paidAt,amount,token,simulatedandshadow; itspayee, by name and address, withbank: truefor a payment to a bank; itsbill, with its number or title, amount, currency and due date;approval.authorizedBy; itstransaction,txHashandchain; andentry, theseqof the entry that records it.rowsShownandrowsTotalsay how many rows it holds, andnotSettledandescrowcount 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,signedEntryProvesandcheckAnEntry. It counts instead the server's own check of each entry the file carries, insignatures:cited,verified,failedandunchecked. 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'sverifyEvidenceand 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
changesShownorrowsShown, with a sentence innotShown.
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
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:
{
"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:
{
"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:
[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:
{
"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, thenlist_invoicesandlist_milestoneswithstatus: "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_counterpartieswithriskLevel: "high", thenget_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_invoicesto find the bill, thenget_invoice_evidence. - "What did October close with, and did every signed entry in the close pack verify?" uses
get_close_packwithmonth: "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_counterpartiesto find Quill Studio, thencreate_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_counterpartiesto find Mona, thencreate_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.