@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.

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

Roadmap (out of v1 scope)

• Remote/hosted transport (Streamable HTTP) in addition to local stdio.
• Read tools: list policies, view accumulated spend.
• OAuth authentication.