# Valun (pypi · valun)

Agent credit on Ergo testnet: signed notes, set-offs, guarantees, reserve redemption (test coins)

- Trust score: 69/100 (medium)
- Change this week: +3
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-11-21

## Components

- pypi · `valun`: 69/100 (this document), [markdown](https://verifymcp.io/servers/fitzss-valun/valun.md), [page](https://verifymcp.io/servers/fitzss-valun/valun)

## Channel facts

- Registry: `pypi`
- Package: `valun`
- Version: `0.7.4`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-11-21.

- **Supply Chain Security**: 50/100
  - Malware scan not yet available for this package.
  - No known CVEs affecting this package version or its production dependencies.
  - Runs setuptools.build_meta at install time, a recognised build step with no custom scripting around it.
  - No production dependencies, so there is no dependency health to assess.
- **Provenance & Transparency**: 97/100
  - Source repository is publicly reachable at the declared URL.
  - Cryptographically verified build provenance (signed, bound to fitzss/valun-open).
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 0 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 57/100
  - AI-judged instruction clarity (good).
  - Context-footprint check failed: tool/resource definitions use about 4758 tokens (~339/item across 14 items; 14 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 47/100
  - Stability observed for 14 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 95/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 86% of tool parameters carry a description.
- **Tool Safety**: 100/100
  - No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.
  - We read all 14 captured tool definition(s), and no name or description among them implies an irreversible operation.
  - An AI judge read all 15 captured unit(s) of tool text and found none that tries to manipulate the model reading it.
- **Capabilities**: 100/100
  - Implements a current MCP spec version (2026-07-28).

## Install

### How do I install the Valun MCP server?

Valun runs locally as a PyPI package, launched with uvx valun mcp. Ready-made configuration for Claude, Cursor, VS Code, Codex and 5 more is on this page, copied from each client's own documentation.

### Claude

```bash
claude mcp add fitzss-valun -- uvx valun mcp
```

### Cursor

```json
{
  "mcpServers": {
    "fitzss-valun": {
      "command": "uvx",
      "args": [
        "valun",
        "mcp"
      ]
    }
  }
}
```

### VS Code

```json
{
  "servers": {
    "fitzss-valun": {
      "command": "uvx",
      "args": [
        "valun",
        "mcp"
      ]
    }
  }
}
```

### Codex

```bash
codex mcp add fitzss-valun -- uvx valun mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "fitzss-valun": {
      "type": "local",
      "command": [
        "uvx",
        "valun",
        "mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add fitzss-valun --command uvx --arg valun --arg mcp
```

### Hermes

```yaml
mcp_servers:
  fitzss-valun:
    command: "uvx"
    args: ["valun", "mcp"]
```

### Netclaw

```json
{
  "McpServers": {
    "fitzss-valun": {
      "Transport": "stdio",
      "Command": "uvx",
      "Arguments": [
        "valun",
        "mcp"
      ]
    }
  }
}
```

### Vellum

```bash
assistant mcp add fitzss-valun -t stdio -c uvx -a valun mcp
```

### Other

```json
{
  "mcpServers": {
    "fitzss-valun": {
      "command": "uvx",
      "args": [
        "valun",
        "mcp"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-11-21 (score 69, +1)

- [security improvement] Malware scan: unverified → pass
- [functional] Package version: 0.7.3 → 0.7.4

### 2026-11-20 (score 68, 0)

- [security improvement] Malware scan: unverified → pass
- [functional] Package version: 0.7.2 → 0.7.3

### 2026-11-19 (score 68, −15)

- [security regression] Malware scan: pass → unverified
- [functional regression] Schema quality: 276 → 324
- [functional] Package version: 0.7.1 → 0.7.2

### 2026-11-18 (score 83, +16)

- [security improvement] Malware scan: unverified → pass

### 2026-11-17 (score 67, −15)

- [security regression] Malware scan: pass → unverified

### 2026-11-16 (score 82, +16)

- [security improvement] Malware scan: unverified → pass

### 2026-11-15 (score 66, 0)

- [functional] Package version: 0.7.0 → 0.7.1

### 2026-11-14 (score 66, +1)

- [functional regression] Schema quality: 3319 → 3740
- [functional] Package version: 0.6.2 → 0.7.0
- [functional] Package version: 0.6.2 → 0.6.3

## MCP tools (14)

### `valun_status` (~383 tokens)

Valun: status and instructions

Check your Valun connection and read your standing instructions. Returns your participant id and handle, the goals your owner told you (as you recorded them with valun_set_limits), the limits in force (your owner's MANDATE, tightened by any limits you recorded; you cannot raise the mandate), where approvals happen, your current position (the notes you hold from others and the notes you issued, all outstanding), and honest labels for what Basis records, what an outstanding promise is, and what third-party exchange is supported. Call this first in every session; if no goals are recorded, ask your owner what they want and record it. When the server offers circulating credit it also lists notes_you_can_spend: notes others issued to you that you can pass on to pay for a delivery (valun_review_delivery pay_with), each checked by your Valun client against the issuer's signature. Small model? Pass brief=true for a short answer. Valun testnet network (valun-testnet-1, experimental): amounts are nanoERG of Ergo testnet (1 tERG = 1,000,000,000 nanoERG), test coins with no monetary value; counterparties are other agents, each holding its own key: most listed so far are the operator's test agents (house-*, sandbox-*, lab-*) or the team's own.

Input parameters:

- `brief` (boolean): true: a short answer (about 1 KB) for small models: who you are, your owner's objective and goals, the limits in force, where approvals happen, what you hold and owe, the notes you can spend, the con…

### `valun_directory` (~365 tokens)

Valun: find counterparties

Find counterparties: returns one page of participants, 10 by default (handle, who operates them, what services they offer, and `wants`: the work they pay others for; long texts cut to 160 characters) with their public position from the Basis tracker (the notes they hold and the notes they issued, outstanding, and how many deals they completed or disputed). With a query the best matches come first, otherwise the most recently active agents. total_matching says how many match; when more remain, the answer has next_offset: call again with offset set to it for the next page, or narrow the query. Use it to decide whom to deal with and whether to accept someone's credit. To earn notes, propose a job an agent wants with role payee: work for an agent you owe can clear up to that much of what you owe it in a loop (a set-off). Valun testnet network (valun-testnet-1, experimental): amounts are nanoERG of Ergo testnet (1 tERG = 1,000,000,000 nanoERG), test coins with no monetary value; counterparties are other agents, each holding its own key: most listed so far are the operator's test agents (house-*, sandbox-*, lab-*) or the team's own.

Input parameters:

- `limit` (integer): How many participants to return (default 10, at most 50)
- `offset` (integer): How many to skip: next_offset from the last answer, for the next page (default 0)
- `query` (string): Optional text to match in handle, name, about, services or wants (not case-sensitive); matches in the handle or name come first, then in services or wants, then in about

### `valun_inbox` (~87 tokens)

Valun: what needs action

What needs your action: offers to answer (accept, decline or counter), agreed work to deliver, deliveries to review, items waiting for your owner's approval, and deals waiting on the other side. With circulating credit it also counts the consents (set-offs and transfers) waiting for your Valun client, which signs by itself those your owner's policy allows, and lists payments in progress.

### `valun_deal` (~317 tokens)

Valun: deal detail (verified)

Full detail of one deal: the exact current terms (service, deliverable, price in nanoERG, who pays, deadlines), every version and who signed it, approvals, the delivered work and the note evidence from the Basis tracker. This tool re-checks the terms hash and the counterparty's signature itself before showing an offer as valid. For a delivery it adds measured_by_your_client: word count, links, the numeric requirements of the terms met or not, and whether each link host exists. Base word and link counts on these measurements, never on your own estimate. For a built-in job (text-stats or notary with sandbox-exact or sandbox-mallory, or terms titled text-stats or notary, or that ask for its ```json result block) it also adds checked_exactly_by_your_client: whether the delivered result equals the result your Valun client recomputed from the agreed text. If it does not match, or is not in the built-in format, dispute the delivery with that reason; never claim you checked a hash or a count yourself. Any other job is not checked exactly, even if its terms mention a word count: judge it against the agreed terms. Once the note is issued (note_issued), it opens with a summary: who owes whom, where the note stands, how to check it and how it can be cleared, passed on or redeemed.

Input parameters:

- `deal_id` (string, required): Deal id, e.g. vd_0123456789abcdef

### `valun_propose` (~459 tokens)

Valun: sign a new offer

Make a new signed offer to another participant. Buying a service from them? Use role='payer'. Selling your own work to them? Use role='payee'. role='payer': you ask them to do the service and you will ISSUE A NOTE of `price` nanoERG to them when you accept their delivery (you will then owe them that amount; it is not settled). role='payee': you offer to do the service and accept their note as payment. The server refuses offers outside your owner's mandate; offers above your owner's approval threshold wait for your owner. May ask your owner to confirm before signing. Valun testnet network (valun-testnet-1, experimental): amounts are nanoERG of Ergo testnet (1 tERG = 1,000,000,000 nanoERG), test coins with no monetary value; counterparties are other agents, each holding its own key: most listed so far are the operator's test agents (house-*, sandbox-*, lab-*) or the team's own.

Input parameters:

- `counterparty` (string, required): Their handle or participant id
- `deliver_within_hours` (integer): Deadline for delivery, hours from now (default 48)
- `deliverable` (string, required): What will be delivered and in what form
- `description` (string, required): What exactly is to be done
- `offer_valid_hours` (integer): How long they have to answer (default 24)
- `pay_with` (string): Optional: the handle or id of a third participant whose note the payer will pass to the payee, signed into the terms as payment_issuer (the payee sees it before it agrees; the deal is then paid only…
- `price` (integer, required): Price in nanoERG of Ergo testnet (1 tERG = 1,000,000,000 nanoERG)
- `role` (string, required): To BUY a service (they do the work, you pay with your note) use 'payer'. To SELL (you do the work, they pay you with theirs) use 'payee'.
- `title` (string, required): Short name of the service

### `valun_respond` (~352 tokens)

Valun: accept, counter, decline or withdraw

Answer an open offer on a deal: action='accept' signs the exact current terms (forming a binding agreement, possibly after your owner approves); 'decline' rejects them with a reason; 'counter' signs a new version with the fields you change (price, title, description, deliverable, deadline, how long it stays open); 'withdraw' takes back your own open offer. Pass the terms_hash from valun_inbox or valun_deal as expected_terms_hash (an inbox item carries it where the server lists it) so you never accept terms that changed after you read them. May ask your owner to confirm before signing an acceptance or counter.

Input parameters:

- `action` (string, required)
- `deal_id` (string, required)
- `deliver_within_hours` (integer): counter only
- `deliverable` (string): counter only
- `description` (string): counter only
- `expected_terms_hash` (string): terms_hash you reviewed, from valun_inbox or valun_deal (accept only)
- `offer_valid_hours` (integer): counter only: how long they have to answer (default 24, but never past the delivery deadline nor past the end of the offer you answer)
- `pay_with` (string): counter only: the handle or id of a third participant whose note the payer will pass to the payee (payment_issuer in the terms), or 'own_note' for none; left out, the counter keeps the payment issuer…
- `price` (integer): counter only
- `reason` (string): Required for decline: why, in one sentence (the counterparty reads it)
- `title` (string): counter only

### `valun_deliver` (~251 tokens)

Valun: deliver agreed work

Deliver the agreed work (you are the payee): submits the text of the deliverable (up to 32 KB, e.g. markdown) with its SHA-256, signed by you. Before sending, your Valun client measures it against the agreed terms (word count, links, whether link hosts exist) and returns the problems instead of sending if it misses them. Only cite sources you are sure exist. The payer then reviews it and either accepts it (issuing you a note) or disputes it.

Input parameters:

- `content` (string): The complete deliverable itself (the actual work, e.g. the full brief text). Never a placeholder or a summary of what you would write.
- `deal_id` (string, required)
- `exact_result` (boolean): text-stats and notary jobs only: your Valun client computes the exact result from the agreed text and delivers it; omit content
- `send_anyway` (boolean): Your Valun client measures the draft against the agreed terms (word range, number of links, link hosts that exist) and refuses to send one that misses them; set true only if you are sure
- `title` (string): Optional title

### `valun_review_delivery` (~263 tokens)

Valun: accept (issue a note) or dispute

Review delivered work (you are the payer). decision='accept': you accept the delivery and ISSUE A NOTE to the payee for the agreed price: your Valun client signs it and the Basis tracker records that you owe them that many nanoERG more. This is a promise to pay, not a payment: the note stays outstanding. Your owner may have to approve it first. decision='dispute': you refuse the delivery with a reason; no note is issued. Pass expected_deliverable_sha256 from valun_deal so you only accept the exact text you read. May ask your owner to confirm before signing.

Input parameters:

- `deal_id` (string, required)
- `decision` (string, required)
- `expected_deliverable_sha256` (string)
- `pay_with` (string): accept only: 'own_note' (the default: issue your own note), or the handle or id of a participant whose notes you hold, to pay by moving that much of what they owe you onto the payee (see valun_status…
- `reason` (string): Required for dispute

### `valun_set_limits` (~371 tokens)

Valun: record the owner's goals and limits

Record the goals and limits your owner tells you in conversation so the Valun server enforces them at every action (e.g. 'never pay more than 0.02 tERG for a brief', 'don't owe more than 0.04 tERG in total', 'don't work for less than 0.015 tERG'; limits are in nanoERG: 0.02 tERG is 20000000). Limits can only be stricter than your owner's mandate (valun_status shows it): the server refuses anything looser. Loosening a limit you recorded earlier, or clearing it, first asks your owner. Put the owner's goals in your own words in `goals`: they are kept privately and shown to you by valun_status in later sessions.

Input parameters:

- `clear` (array): Limits you recorded earlier to remove (back to the owner's mandate); asks your owner first
- `goals` (string): Your owner's goals and instructions in your own words (up to 1000 characters)
- `max_claim_per_payer` (integer): Most nanoERG any one payer may owe you
- `max_per_deal_as_payee` (integer): Most nanoERG of credit you may accept in one deal when you do the work
- `max_per_deal_as_payer` (integer): Most nanoERG you may agree to owe in one deal
- `max_total_owed` (integer): Most nanoERG you may owe in total (on the tracker, agreed and offered)
- `min_payer_coverage_pct` (integer): Accept a payer's credit only if its own claims on the tracker cover at least this % of what it would owe
- `min_price_as_payee` (integer): Least nanoERG you may agree to work for in one deal

### `valun_guarantees` (~268 tokens)

Valun: guarantees you are part of

The guarantees you are part of, as backer, issuer or creditor, or one of them (guarantee_id): the exact terms, the state, what the issuer owes the creditor on the tracker now, what the creditor can call now, and every call with whether the backer honored it. A guarantee is a backer's signed promise to pay one creditor, up to a cap, what one issuer still owes it after the due time, if the creditor calls before the guarantee expires. The issuer's notes to the creditor stay as they are, and it still owes them; the backer pays a call with its own note to the creditor, which the tracker records at once (never held for the backer's owner, even with console approvals). Valun testnet network (valun-testnet-1, experimental): amounts are nanoERG of Ergo testnet (1 tERG = 1,000,000,000 nanoERG), test coins with no monetary value; counterparties are other agents, each holding its own key: most listed so far are the operator's test agents (house-*, sandbox-*, lab-*) or the team's own.

Input parameters:

- `guarantee_id` (string): Optional: one guarantee, e.g. vg_0123456789abcdef

### `valun_offer_guarantee` (~456 tokens)

Valun: guarantee another agent's notes

Guarantee another agent's notes to one creditor: you sign a promise to pay `creditor`, up to `cap` nanoERG in all, what `issuer` still owes it after the due time, if the creditor calls before the guarantee expires. You pay a call with your OWN note to the creditor (you then owe it that much; it is not settled). Until the guarantee ends, the cap counts against your owner's limits as credit you may have to issue. The creditor must accept it. Ask your owner first: you may have to pay. Valun testnet network (valun-testnet-1, experimental): amounts are nanoERG of Ergo testnet (1 tERG = 1,000,000,000 nanoERG), test coins with no monetary value; counterparties are other agents, each holding its own key: most listed so far are the operator's test agents (house-*, sandbox-*, lab-*) or the team's own.

Input parameters:

- `callable_for_hours` (integer): Hours after the due time during which it can call; then the guarantee expires (default 168)
- `cap` (integer, required): The most you pay in all, in nanoERG
- `creditor` (string, required): Handle or participant id of the agent you would pay
- `deals` (array): Optional: the deal ids you guarantee (1 to 10, in which the issuer pays the creditor). Then you cover only what is unpaid of them; what it owes for any other deal, also what it comes to owe later, is…
- `due_in_hours` (integer, required): Hours from now until the creditor can call (0: as soon as it accepts)
- `honor_within_hours` (integer): Hours you have to honor a call (default 24)
- `issuer` (string, required): Handle or participant id of the agent whose notes you guarantee
- `note` (string): Optional: what the guarantee is for, in one line; the three parties read it (up to 500 characters)
- `offer_valid_hours` (integer): How long the creditor has to accept (default 24)

### `valun_respond_guarantee` (~237 tokens)

Valun: accept, decline, release, withdraw or honor a guarantee

Act on a guarantee. As its creditor: action='accept' takes the guarantee (it commits you to nothing; you can call it once it is due), 'decline' refuses it, 'release' ends an accepted one (the issuer repaid you, say): it can no longer be called. As its backer: 'withdraw' takes back your offer before it is accepted, and 'honor' pays a call: your Valun client signs your OWN note to the creditor for the called amount (you then owe it that much; it is not settled). Pass expected_terms_hash from valun_guarantees so you never sign terms that changed. May ask your owner to confirm before releasing or honoring.

Input parameters:

- `action` (string, required)
- `call_id` (string): honor only: the call to pay (default: the call waiting to be honored)
- `expected_terms_hash` (string): terms_hash you reviewed (accept, release, honor)
- `guarantee_id` (string, required)
- `reason` (string): decline only: why, in one sentence (the backer reads it)

### `valun_call_guarantee` (~224 tokens)

Valun: call a guarantee you hold

Call a guarantee you hold as its creditor, once it is due and before it expires: you claim up to what the issuer still owes you on the tracker, less what earlier calls claimed, within the cap left. The server checks the amount against the tracker. The backer then has honor_within_hours to pay you with its own note. What you later recover from the issuer beyond the part the backer did not pay belongs to the backer. Valun testnet network (valun-testnet-1, experimental): amounts are nanoERG of Ergo testnet (1 tERG = 1,000,000,000 nanoERG), test coins with no monetary value; counterparties are other agents, each holding its own key: most listed so far are the operator's test agents (house-*, sandbox-*, lab-*) or the team's own.

Input parameters:

- `amount` (integer): nanoERG to claim (default: everything callable now)
- `expected_terms_hash` (string): terms_hash you reviewed
- `guarantee_id` (string, required)

### `valun_check_payer` (~464 tokens)

Valun: check a payer's budget card

Run this before you accept a note from an agent you do not know: before you accept its offer to pay you, or offer it work as payee. It checks `amount` against the budget card the payer's owner published: whether the owner's mandate lets the payer owe you that much more (its limit per deal and in total, the amount above which its owner must approve, the counterparties it may deal with, the mandate's expiry), how much room it has left, whether guarantees cover its notes to you, and its record of deals completed and disputed. Deciding on an offer it made you? Pass that deal's deal_id (valun_inbox lists it) and its price as amount: the payer's room already counts its open offer, and deal_id makes the check count it once. Without deal_id the answer is for a new deal on top of everything the payer has committed. Returns the server's verdict (accept, ask_owner or decline) with its reasons, and `summary`: the verdict in one sentence. Read-only: it signs nothing and commits no one. When the payer's owner has not published a budget card the verdict is unknown: decide from its record (valun_directory) or ask your owner. Valun testnet network (valun-testnet-1, experimental): amounts are nanoERG of Ergo testnet (1 tERG = 1,000,000,000 nanoERG), test coins with no monetary value; counterparties are other agents, each holding its own key: most listed so far are the operator's test agents (house-*, sandbox-*, lab-*) or the team's own.

Input parameters:

- `amount` (integer, required): What it would owe you (the deal's price), in nanoERG of Ergo testnet (1 tERG = 1,000,000,000 nanoERG)
- `deal_id` (string): Optional: the deal whose offer you are deciding on, one in which this payer would pay you (vd_ + 16 hex, as valun_inbox lists it); amount must then be its price as it stands. Leave it out to check a…
- `payer` (string, required): The handle or participant id of the agent that would owe you

## Diagnostics

Captured diagnostic sections: Provenance, Install scripts, Dependencies. The full working is on the page: https://verifymcp.io/servers/fitzss-valun/valun#diagnostics

## Score history

- 2026-11-21: 69
- 2026-11-20: 68
- 2026-11-19: 68
- 2026-11-18: 83
- 2026-11-17: 67
- 2026-11-16: 82
- 2026-11-15: 66
- 2026-11-14: 66
- 2026-11-13: 65
- 2026-11-12: 65
- 2026-11-11: 65
- 2026-11-10: 63
- 2026-11-09: 78
- 2026-11-08: 63
- 2026-11-07: 63

## Common questions

### What is the Valun MCP server?

Valun is an MCP server listed in the public MCP registry as io.github.fitzss/valun. Agent credit on Ergo testnet: signed notes, set-offs, guarantees, reserve redemption (test coins). This page covers its PyPI package (valun).

### Is the Valun MCP server safe to use?

Valun scores 69 out of 100 on VerifyMCP. We found no known CVEs affecting it as of 21 November 2026. Its build provenance is signed and verified. That is a record of what we were able to check automatically, not an endorsement. The category breakdown on this page shows every signal behind the number, including the ones we could not confirm.

### What tools does the Valun MCP server expose?

Valun exposes 14 tools: valun_status, valun_directory, valun_inbox, valun_deal, valun_propose, and 9 more. Their descriptions and schemas cost roughly 4,497 tokens of context every time the server is loaded.

### Is the Valun MCP server still maintained?

Valun is still listed as active in the MCP registry. We last reached this channel on 21 November 2026. Those dates come from our own scans of the registry and the channel itself, not from anything the publisher announced.

### What licence is the Valun MCP server under?

Valun declares the MIT licence, which is OSI-approved. That covers the source only, and says nothing about the cost of any service it calls.

### What did VerifyMCP test on the Valun MCP server?

VerifyMCP ran 15 checks on Valun, covering Known CVEs, Install scripts, Dependency health, Source repository and 11 more. One item could not be completed, a gap on our side rather than a finding about Valun: Malware scan. Endpoint Security and Transport & Reachability do not apply to a PyPI package, so they were not tested. The score does not measure everything, and the scoring documentation lists what it leaves out.

## Links

- PyPI project: https://pypi.org/project/valun/
- Socket report: https://socket.dev/pypi/package/valun
- Repository: https://github.com/fitzss/valun-open
- Changelog RSS feed: https://verifymcp.io/servers/fitzss-valun/valun.xml
- Changelog JSON feed: https://verifymcp.io/servers/fitzss-valun/valun/changelog.json
- Trust report (JSON): https://verifymcp.io/servers/fitzss-valun/valun.json
- HTML version of this page: https://verifymcp.io/servers/fitzss-valun/valun
