Docs · updated 2 Nov 2026
MCP server setup
nevarn-mcp is a local Model Context Protocol server that gives an AI agent the same calls as the SDKs: propose_intent, execute_intent, get_execution, get_mandate, get_receipt and halt, beside request_spend. It runs on your machine over stdio with your API key, and it adds no authority: a model talked into anything is still bounded by the key's scopes and limits, your account's limits and Decionis.
The packages are not yet published to PyPI or npm, and their source repository is not public yet. Until they are, everything they do is available over the HTTP API in the strategy contract; the SDKs add local checks and typed errors on top.
The SDKs and the MCP server are free to download and use under the Apache License 2.0. Using the Nevarn platform they call is licensed on the platform, by governed actions or by subscription.
1. Install the server
Build it from a copy of the source, or install the packed file into a project of your own (see Install and downloads). Either gives you a command your MCP client can start: node with the built server's path, or the nevarn-mcp the install puts in node_modules/.bin. It needs Node.js 20 or later.
2. Mint a key for the agent
Give the agent its own API key, with only the scopes it needs (see API keys and scopes). The key is the agent's whole authority.
| The agent should | Scopes |
|---|---|
| Read your bounds and receipts only | read |
| Propose intents for shadow rulings, and stop everything if something looks wrong | intents, read, halt |
| Also place orders, within limits you set on the key | intents, read, halt, execute |
| File supplier invoices for your payables policy | invoices |
3. Configure your client
Add an entry for the server to your MCP client's configuration; your client's own documentation says where that file is. The shape below is the usual mcpServers entry: a command, its arguments and two environment variables.
{
"mcpServers": {
"nevarn": {
"command": "node",
"args": ["/path/to/nevarn-source/apps/mcp/dist/Main.js"],
"env": {
"NEVARN_BASE_URL": "https://api.nevarn.com",
"NEVARN_API_KEY": "nvk_…"
}
}
}
}Installed into a project instead, the command is that project's node_modules/.bin/nevarn-mcp, with no arguments.
| Variable | Required | What |
|---|---|---|
| NEVARN_BASE_URL | Yes | The platform's address, https://api.nevarn.com. https only (plain http only on 127.0.0.1, localhost or [::1]); there is no default. |
| NEVARN_API_KEY | Yes | An nvk_ API key. A session token is refused. The key is never a tool argument and never appears in a tool result or a log. |
On start the server writes one JSON line to stderr: started, its version and the names of its seven tools. If either variable is missing or refused, it writes configuration_refused and exits with status 2.
Tools
| Tool | Scope | Inputs | What it does |
|---|---|---|---|
| propose_intent | intents | strategy (polymarket, sports, capital or arbitrage), intent_key, intent | Asks for a shadow ruling on an intent. Nothing is sent to a venue; the result says whether it would have executed and why not. |
| execute_intent | execute | strategy (polymarket or sports), intent_key, intent | Executes an intent within the key's limits: a paper fill in Sandbox, a live order ruled in enforcement right before the venue in Production. Marked destructive, so your client asks before it runs. |
| get_execution | execute | execution_id | Reads one execution and its current state. Read-only. |
| get_mandate | read | None | Reads your limits, signing grants, payables policy and, per strategy, the Decionis policy and the maximum intent age; where executions go, with the key's execute limits; and this month's governed actions. Read-only. |
| get_receipt | read | receipt_id (the execution's id) | Reads one execution receipt: ruling, order, fill, settlement, ledger entries, balance. Read-only. |
| halt | halt | reason (optional, 500 characters at most) | Turns all signing off and stops your bots' unsent executions. Calling it twice is harmless. There is no resume tool. |
| request_spend | invoices | vendor_id, invoice_number, amount_minor, destination_address; optional asset_code (USDC), chain_id (137), due_at, proof_hash | Files a supplier invoice for your payables policy to decide. Filing the same invoice again is refused with a conflict (409). |
intent_key is the agent's idempotency key: 1 to 160 characters of letters, digits and _ . : -, starting with a letter or digit. The same key with the same terms returns the first answer, so an agent may retry safely; the same key with other terms is refused. Amounts are integers in the venue's units, and observed_at must be recent: get_mandate gives each strategy's max_intent_age_seconds.
Guarantees
- Tool names, descriptions and schemas are fixed in the server; nothing the platform returns is ever written into them.
- Every schema refuses fields it does not name, including one strict shape per strategy's intent; an intent carrying anything named like a secret is refused before any call.
- Results are JSON data, and any text inside them is data, not instructions. Errors carry only a type, status, code and route.
- Logs go to stderr as JSON lines; stdout is the protocol channel.
- There is no hosted Nevarn MCP endpoint: the server runs where your agent does.