@riv-io/mcp

@riv-io/mcp

MCP server for Riv — the entry point for connecting agents. Instead of writing the HTTP authorization call into your agent's code, the developer connects riv-mcp as an MCP server in their client and the agent gets the authorize and get_activity tools ready to use.

It's a thin shell over the Riv API (POST /api/v1/authorize and GET /api/v1/activities): it doesn't reimplement authentication, the decision engine or the ledger — it just receives the tool call, calls the HTTP API with the riv_key and returns the result.

The tools

authorize({ amount, currency, description?, category? })

Asks Riv whether a transaction is allowed before executing it.

• amount (number, > 0, up to 2 decimals) — the transaction value.
• currency (string) — currency, e.g. BRL, USD.
• description (string, optional) — description for audit.
• category (string, optional) — spend category (e.g. inference, saas); per-category mandates use this. Normalized (lowercased) on the server; with no category, only general policies apply.

Returns a text with the governance decision:

Decision: ALLOW | BLOCK | REQUIRE_APPROVAL
Reason: <policy reason>
activityId: <ledger record id>

BLOCK and REQUIRE_APPROVAL are valid decisions (not errors). Real call failures — invalid credential (401), invalid input (400) or network — return with isError: true and a distinct message, so the agent doesn't confuse "failure" with "block".

get_activity({ activityId?, limit? })

Queries the Riv ledger — always scoped to the agent itself (the riv_key).

• activityId (string UUID, optional) — point lookup: the result of a specific authorization, using the id returned by the authorize tool.
• limit (integer 1–50, optional, default 10) — how many recent activities to return in the statement. Ignored when activityId is provided.

Without activityId, returns the recent statement. Each line:

<createdAt ISO>  APPROVED | PENDING | BLOCKED | REJECTED  <amount> <currency> (<type>)
  activityId: <id>
  category: <if any>
  description: <if any>

A missing activityId (or one from another agent) → 404 and isError: true.

PENDING is resolved by a human in the Riv dashboard: it becomes APPROVED (starts counting toward accumulated spend) or REJECTED (doesn't count). BLOCKED is always an engine verdict. Query the activity again to see the outcome.

Configuration in the MCP client

Transport: stdio (local). The client spawns the server and talks over stdin/stdout.

{
  "mcpServers": {
    "riv": {
      "command": "node",
      "args": ["/path/to/riv/mcp/dist/index.js"],
      "env": {
        "RIV_API_KEY": "riv_...",            // the agent's credential (required)
        "RIV_API_URL": "http://localhost:3000" // API base (defaults to this value)
      }
    }
  }
}

Once published to npm, you can skip the local path and run it with npx:

{
  "mcpServers": {
    "riv": {
      "command": "npx",
      "args": ["-y", "@riv-io/mcp"],
      "env": { "RIV_API_KEY": "riv_...", "RIV_API_URL": "https://riv-io.vercel.app" }
    }
  }
}

• RIV_API_KEY — required; the riv_key issued when you connect the agent in Riv. Without it the server exits on startup with an error on stderr.
• RIV_API_URL — optional; defaults to http://localhost:3000 (local dev). For agents in production, use https://riv-io.vercel.app. Validated on startup: only http: or https:, and https:// is required unless the host is localhost, 127.0.0.1 or [::1] (the riv_key travels in the Authorization header and must not cross the network in the clear). An invalid URL exits with an error on stderr.

Development

cd mcp
npm install
npm run build        # tsc → dist/
npm run typecheck    # type check without emitting

# E2E (from the repo root; the harness spins up the app on an ephemeral port —
# requires `npm run build` at the root and `npm run build` here in mcp/):
#   node --env-file=.env scripts/verify-mcp.mjs

Checklist de publicação

Publicar no npm é passo de go-live — nunca parte do fluxo normal de desenvolvimento.

• npm publish roda prepublishOnly automaticamente (typecheck + build); se qualquer um falhar, nada é publicado.
• Antes de publicar, inspecione o conteúdo do tarball com npm pack --dry-run: apenas dist/ (+ package.json, README.md, LICENSE) deve aparecer — nunca src/, testes, .env ou qualquer configuração local.
• A publicação em si só acontece no go-live, junto com os demais pacotes @riv-io/* (versões saem em lote).

Trading tools (0.2.0 — Trading Guard)

Seven tools expose Riv's governed trading surface. Point your agent at this MCP server instead of a raw exchange MCP: every order goes through Riv's policy engine and gateway (leverage caps, position limits, loss halts, trading hours, human approval), and executed orders carry Riv's builder code. BLOCK and REQUIRE_APPROVAL are normal outcomes, not errors — read the Reason/ReasonCode and adapt (reduce size or leverage, switch asset, or wait for approval).

• place_order({ asset, side, orderType, notional, leverage, reduceOnly? }) — evaluates the order against the org's trading policies and, with an active venue connection, executes it. Returns Decision, Reason, ReasonCode, Executed, VenueOrderId and the ledger activityId. Only market orders are executable today (limit is evaluated but not submitted).
• get_positions() — open positions from Riv's view of the account (refreshed from the venue when stale; may take a few seconds).
• get_account_state() — equity, peak equity, daily realized PnL, consecutive losses and open positions — the same state the policies evaluate against.
• get_market_data({ asset }) — read-only mid/mark price, hourly funding rate and open interest. No custodial connection required.
• cancel_order({ asset, venueOrderId }) — cancels a resting order via the gateway. A failed cancel (e.g. already filled) is a normal outcome.
• close_position({ asset }) — closes the position with a governed reduce-only market order in the opposite direction (same policy engine as place_order; reduce-only passes loss halts by design).
• list_trading_policies() — human-readable summary of the policies in effect. With no policies, all orders are blocked by default (fail-closed).

Roadmap (out of v1 scope)

• Remote/hosted transport (Streamable HTTP) in addition to local stdio.
• Read tools for spend: view accumulated spend.
• OAuth authentication.
• EN harmonization for the legacy authorize/get_activity tools (the shared 10s timeout landed in 0.2.0).