Skip to content

feat(mcp): single-source the tool surface, add read-only mode, paid-operation policy, and concurrency tests #768

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
manoahLinks merged 4 commits into from
Aug 31, 2026
+3,892 −805
Merged

feat(mcp): single-source the tool surface, add read-only mode, paid-operation policy, and concurrency tests #768

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3bc826e
fix(mcp): repair merge damage that left the package uncompilable
devylongs Aug 30, 2026
b81b880
feat(mcp): single-source the tool surface, add read-only mode and a p…
devylongs Aug 30, 2026
afbcbcc
test(mcp): add concurrent state write regression tests
devylongs Aug 30, 2026
5958b5d
test(mcp): fix a flaky correlation-id uniqueness assertion
devylongs Aug 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 49 additions & 13 deletions docs/environment-variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -163,24 +163,60 @@ All other variables are either public addresses or non-sensitive configuration.

## MCP

| Variable | Required | Default | Description |
| ----------------------------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------- |
| `STELLAR_NETWORK` | no | `testnet` | MCP deployment target (`testnet` or `mainnet` / `pubnet` / `public`). |
| `MINDVAULT_ALLOW_MAINNET` | no | unset | Set to `1` / `true` to allow gated MCP mutations and buys on mainnet without per-call `confirmMainnet`. |
| `MINDVAULT_HTTP_TIMEOUT_MS` | no | `15000` | Request deadline for the MindVault API and sponsored-account service. `0` disables. |
| `MINDVAULT_HORIZON_TIMEOUT_MS` | no | `15000` | Request deadline for Horizon balance/account reads. `0` disables. |
| `MINDVAULT_SOROBAN_TIMEOUT_MS` | no | `20000` | Request deadline for Soroban RPC calls. `0` disables. |
| `MINDVAULT_PAYMENT_TIMEOUT_MS` | no | `45000` | Request deadline for x402 paid fetches, which include on-chain settlement. `0` disables. |
| `MINDVAULT_RETRY_ATTEMPTS` | no | `3` | Total attempts (including the first) for idempotent MCP calls. `1` disables retrying. |
| `MINDVAULT_RETRY_BASE_DELAY_MS` | no | `250` | Backoff delay before the first retry; doubles each attempt. |
| `MINDVAULT_RETRY_MAX_DELAY_MS` | no | `4000` | Ceiling on the backoff delay before jitter is applied. |
| `MINDVAULT_PREVIEW_MAX_BYTES` | no | `8192` | Byte ceiling for a `mindvault_preview` response. `0` disables; values below `1024` are raised to it. |
| `MINDVAULT_PREVIEW_FIELD_MAX_CHARS` | no | `1000` | Character ceiling for each free-text preview field (`title`, `description`). `0` disables. |
| Variable | Required | Default | Description |
| ----------------------------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `STELLAR_NETWORK` | no | `testnet` | MCP deployment target (`testnet` or `mainnet` / `pubnet` / `public`). |
| `MINDVAULT_ALLOW_MAINNET` | no | unset | Set to `1` / `true` to allow gated MCP mutations and buys on mainnet without per-call `confirmMainnet`. |
| `MINDVAULT_READ_ONLY` | no | unset | Set to `1` / `true` / `yes` / `on` to restrict the MCP server to catalog browsing. Only read-only tools are advertised and all others are refused. |
| `MINDVAULT_CONFIRM_PAID_OPERATIONS` | no | `off` | `off`, `usdc`, or `all`. Requires `confirmPaid: true` on tools that spend, independently of network. An unrecognized value is an error, not a fallback. |
| `MINDVAULT_HTTP_TIMEOUT_MS` | no | `15000` | Request deadline for the MindVault API and sponsored-account service. `0` disables. |
| `MINDVAULT_HORIZON_TIMEOUT_MS` | no | `15000` | Request deadline for Horizon balance/account reads. `0` disables. |
| `MINDVAULT_SOROBAN_TIMEOUT_MS` | no | `20000` | Request deadline for Soroban RPC calls. `0` disables. |
| `MINDVAULT_PAYMENT_TIMEOUT_MS` | no | `45000` | Request deadline for x402 paid fetches, which include on-chain settlement. `0` disables. |
| `MINDVAULT_RETRY_ATTEMPTS` | no | `3` | Total attempts (including the first) for idempotent MCP calls. `1` disables retrying. |
| `MINDVAULT_RETRY_BASE_DELAY_MS` | no | `250` | Backoff delay before the first retry; doubles each attempt. |
| `MINDVAULT_RETRY_MAX_DELAY_MS` | no | `4000` | Ceiling on the backoff delay before jitter is applied. |
| `MINDVAULT_PREVIEW_MAX_BYTES` | no | `8192` | Byte ceiling for a `mindvault_preview` response. `0` disables; values below `1024` are raised to it. |
| `MINDVAULT_PREVIEW_FIELD_MAX_CHARS` | no | `1000` | Character ceiling for each free-text preview field (`title`, `description`). `0` disables. |

Timeouts are enforced with `AbortController`. Retries apply to idempotent calls only — catalog `GET`s, Horizon reads, and Soroban `getTransaction` — and never to x402 payments, which could settle twice. See [`mcp-timeouts-retries.md`](./mcp-timeouts-retries.md) for budgets, policy, and tuning guidance.

On mainnet, MCP tools that mutate state or spend funds (`mindvault_buy`, `mindvault_publish`, `mindvault_register`, `mindvault_register_onchain`, `mindvault_setup_wallet`, `mindvault_reset`, `mindvault_update_metadata`, `mindvault_set_price`, `mindvault_transfer_ownership`, `mindvault_set_listed`) require either `confirmMainnet: true` on the tool call or `MINDVAULT_ALLOW_MAINNET=1`. Read-only tools are unrestricted. See [`mainnet-deployment-checklist.md`](./mainnet-deployment-checklist.md#mcp-mainnet-guardrails).

### MCP read-only mode

`MINDVAULT_READ_ONLY=1` turns the MCP server into a catalog browser. It is set on the server process and cannot be lifted by a tool argument — unlike `confirmMainnet`, which an agent supplies from inside the very call you wanted to prevent.

Two things change together. `tools/list` advertises only tools whose definition declares `readOnlyHint: true`, so an agent does not plan around a tool it cannot use; and the dispatcher refuses every other tool, so a client working from a cached tool list — or guessing a name — is still stopped. The refusal names the tools that remain available.

Read-only classification comes from the `readOnlyHint` annotation each tool already advertises, so a tool added later is covered by whatever it declares about itself.

```
MINDVAULT_READ_ONLY=1
```

Browsing, search, preview, registry lookups, wallet info, purchase history, and the diagnostic tools stay available. Everything that mutates state, spends funds, or changes stored credentials is refused — including dry runs, which are exempt from the paid-operation policy below but not from this one: read-only mode is about what the server is for, not about what a call costs.

### MCP paid-operation confirmation

`MINDVAULT_CONFIRM_PAID_OPERATIONS` requires an explicit `confirmPaid: true` before a tool spends from the agent wallet. It is independent of the network (unlike the mainnet guardrail, which never fires on testnet) and of the amount (unlike `MINDVAULT_MAX_AUTO_PAY_USDC`, which stops one large purchase but not a hundred small ones).

| Value | Effect |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `off` | Default. No confirmation required. The mainnet guardrail and the auto-pay ceiling still apply. |
| `usdc` | `mindvault_publish` and `mindvault_buy` require `confirmPaid: true`. |
| `all` | Additionally `mindvault_register_onchain`, `mindvault_update_metadata`, `mindvault_set_price`, `mindvault_transfer_ownership`, and `mindvault_set_listed`. |

```
MINDVAULT_CONFIRM_PAID_OPERATIONS=usdc
```

Dry runs (`dryRun: true` on publish or buy) are never gated — they submit no payment, and requiring confirmation would mean confirming a spend in order to find out what the spend would be. `mindvault_setup_wallet` is not gated either: account creation runs through the sponsored-account service, so the agent's own wallet funds nothing.

The policies compose rather than replace one another. A mainnet buy above the auto-pay ceiling with `MINDVAULT_CONFIRM_PAID_OPERATIONS=usdc` must satisfy all three guardrails; `confirmPaid` does not stand in for `confirmMainnet`, or the reverse.

An unrecognized value (`true`, `1`, `yes`) raises an error on the first paid call rather than silently falling back to `off`. A typo in a safety setting that quietly disables it is worse than one that fails loudly.

---

## Mainnet-Specific Notes
Expand Down
28 changes: 12 additions & 16 deletions docs/mcp-tool-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ For structured JSON results (`structuredContent` + `outputSchema`) see
For client installation and configuration see
[mcp-client-configs.md](mcp-client-configs.md).

**35 tools** as of last generation.
**37 tools** as of last generation.

---

Expand Down Expand Up @@ -44,11 +44,12 @@ For client installation and configuration see

## Publishing & Buying

| Tool | Description | Structured |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `mindvault_register` | Register as a publisher using the agent wallet. The API key is persisted to ~/.mindvault/state.json (mode 0600, key not shown in output) and reloaded on restart so mindvault_publish works across sessions. | text only |
| `mindvault_publish` | Publish a link resource to the MindVault catalog. The resource undergoes AI verification (agent wallet pays ~$0.10 USDC via x402) and is automatically registered on-chain if verified. Returns resource ID, access URL, verification result, and on-chain registration status. Pass dryRun: true to validate inputs without submitting payment. | yes |
| `mindvault_buy` | Pay USDC via x402 and access a resource. Payments above MINDVAULT_MAX_AUTO_PAY_USDC (10 USDC by default) require maxAutoPayUsdc set to at least the resource price. On mainnet, pass confirmMainnet: true (or set MINDVAULT_ALLOW_MAINNET=1). Pass dryRun: true to validate the resource and show intended payment flow without submitting payment. | yes |
| Tool | Description | Structured |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `mindvault_register` | Register as a publisher using the agent wallet. The API key is persisted to ~/.mindvault/state.json (mode 0600, key not shown in output) and reloaded on restart so mindvault_publish works across sessions. | text only |
| `mindvault_publish` | Publish a link resource to the MindVault catalog. The resource undergoes AI verification (agent wallet pays ~$0.10 USDC via x402) and is automatically registered on-chain if verified. Returns resource ID, access URL, verification result, and on-chain registration status. Pass dryRun: true to validate inputs without submitting payment. | yes |
| `mindvault_buy` | Pay USDC via x402 and access a resource. Payments above MINDVAULT_MAX_AUTO_PAY_USDC (10 USDC by default) require maxAutoPayUsdc set to at least the resource price. On mainnet, pass confirmMainnet: true (or set MINDVAULT_ALLOW_MAINNET=1). Pass dryRun: true to validate the resource and show intended payment flow without submitting payment. | yes |
| `mindvault_publish_status` | Poll a published resource's verification and on-chain sync status. Returns verificationStatus (pending, verified, rejected, skipped), listed, onchainStatus, onchainTxHash, and optional verification details. Pass wait: true to poll until verification settles or timeoutMs elapses. Deterministic errors for missing resourceId and 404s. | yes |

## On-chain Management

Expand All @@ -75,9 +76,10 @@ For client installation and configuration see

## Receipts

| Tool | Description | Structured |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `mindvault_export_receipts` | Export receipts for resources this agent has purchased as a schema-versioned document (JSON, or RFC 4180 CSV in the envelope's csv field). Filter by resource, network, and date range. Reports a row count and the summed USDC total, so an agent can reconcile spend without re-reading each purchase. | yes |
| Tool | Description | Structured |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `mindvault_export_receipts` | Export receipts for resources this agent has purchased as a schema-versioned document (JSON, or RFC 4180 CSV in the envelope's csv field). Filter by resource, network, and date range. Reports a row count and the summed USDC total, so an agent can reconcile spend without re-reading each purchase. | yes |
| `mindvault_purchase_history` | List locally persisted purchase receipts from successful mindvault_buy calls (~/.mindvault/purchases.json). Read-only. Optional filters: resourceId and network (exact match, e.g. stellar:testnet). Returns count + purchases (newest first), or an empty list when nothing matches. | yes |

## State Management

Expand All @@ -104,12 +106,6 @@ For client installation and configuration see
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `mindvault_recover_catalog_cache` | Attempt a catalog stale-cache recovery: requests the MCP to refresh or re-fetch catalog index data and provides recovery guidance. Useful when browse results appear stale. | yes |

## Other

| Tool | Description |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mindvault_recover_catalog_cache` | Attempt a catalog stale-cache recovery: requests the MCP to refresh or re-fetch catalog index data and provides recovery guidance. Useful when browse results appear stale. |

---

_This file was generated from `mcp/src/tools.ts` — 35 tools._
_This file was generated from `mcp/src/tools.ts` — 37 tools._
11 changes: 11 additions & 0 deletions mcp/.env.example
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,17 @@ SPONSORED_ACCOUNT_URL=https://stellar-sponsored-agent-account.onrender.com
# Disabled unless set to 1/true/yes/on. Query with the mindvault_metrics tool.
# MINDVAULT_METRICS=1

# Read-only mode: restrict this server to catalog browsing. Only tools that
# declare readOnlyHint are advertised in tools/list, and every other tool is
# refused at dispatch. Set on the process — no tool argument can override it.
# MINDVAULT_READ_ONLY=1

# Require explicit confirmPaid: true before a tool spends from the agent wallet,
# regardless of network or amount. off (default) | usdc (publish, buy) | all
# (also the on-chain mutations, which spend network fees). Dry runs are never
# gated. An unrecognized value is an error, not a silent fallback.
# MINDVAULT_CONFIRM_PAID_OPERATIONS=usdc

# Custom User-Agent sent on every outbound HTTP request (MindVault API, Horizon,
# Soroban RPC, sponsored-account service). Useful when you want to identify a
# specific agent or deployment in server logs. Defaults to "mindvault-mcp/1.0.0".
Expand Down
6 changes: 6 additions & 0 deletions mcp/src/__snapshots__/toolMetadata.test.ts.snap
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,8 @@ exports[`MCP tool metadata > exposes the expected tool surface 1`] = `
"mindvault_rotate_publisher_key",
"mindvault_verify_install",
"mindvault_recover_catalog_cache",
"mindvault_publish_status",
"mindvault_purchase_history",
]
`;

Expand All @@ -47,6 +49,10 @@ exports[`MCP tool metadata > mindvault_publish inputSchema 1`] = `
"description": "Required on mainnet (or set MINDVAULT_ALLOW_MAINNET=1). Explicitly confirm this mutation/payment on the public Stellar network.",
"type": "boolean",
},
"confirmPaid": {
"description": "Required when the server runs with MINDVAULT_CONFIRM_PAID_OPERATIONS=usdc or =all. Explicitly confirm that this call may spend from the agent wallet. Ignored when the policy is off (the default) and on dry runs.",
"type": "boolean",
},
"description": {
"description": "Optional detailed description of the resource content (max 2048 characters).",
"examples": [
Expand Down
Loading