Sgovrdocs Back to site
Documentation menu

Documentation

Capability spec

A capability spec is the machine-readable contract a provider publishes. It declares every action - its input and output schemas, pricing, auth scopes and rate limits - so an agent knows exactly what it can do and on what terms before it acts.

Example

A complete spec for a provider exposing a free search_rooms action and a transactional book_room action:

luxhotels.sgovr.json
{
  "sgovrSpecVersion": "0.1",
  "provider": {
    "id": "prov_lux_hotels",
    "name": "Lux Hotels",
    "did": "did:web:luxhotels.example",
    "homepage": "https://luxhotels.example",
    "adapterBaseUrl": "https://adapter.luxhotels.example"
  },
  "mcp": { "compatible": true, "toolNamespace": "luxhotels" },
  "acceptedMandates": ["sgovr-jwt", "ap2-vc"],
  "ap2": { "schemaVersion": "2025.0", "merchantId": "lux_hotels" },
  "actions": [
    {
      "name": "search_rooms",
      "description": "Find available rooms by city, dates and price ceiling.",
      "sideEffects": "none",
      "endpoint": { "method": "POST", "path": "/actions/search_rooms" },
      "pricing": { "model": "free" },
      "rateLimit": { "rpm": 120 },
      "input": {
        "type": "object",
        "required": ["city", "checkIn", "checkOut"],
        "properties": {
          "city": { "type": "string" },
          "checkIn": { "type": "string", "format": "date" },
          "checkOut": { "type": "string", "format": "date" },
          "maxPrice": { "type": "number", "minimum": 0 }
        }
      },
      "output": { "type": "object", "properties": { "rooms": { "type": "array" } } }
    },
    {
      "name": "book_room",
      "description": "Book a specific room for the given dates and charge the guest.",
      "sideEffects": "transactional",
      "endpoint": { "method": "POST", "path": "/actions/book_room" },
      "pricing": { "model": "per_transaction", "takeRateBps": 150 },
      "auth": { "scopes": ["booking:write", "payments:charge"] },
      "rateLimit": { "rpm": 30 },
      "refundable": true,
      "ap2Sku": "lux_hotels_room_night",
      "input": {
        "type": "object",
        "required": ["roomId", "checkIn", "checkOut", "guestName"],
        "properties": {
          "roomId": { "type": "string" },
          "checkIn": { "type": "string", "format": "date" },
          "checkOut": { "type": "string", "format": "date" },
          "guestName": { "type": "string" }
        }
      },
      "output": {
        "type": "object",
        "properties": {
          "bookingId": { "type": "string" },
          "status": { "type": "string" },
          "totalCharged": { "type": "number" },
          "currency": { "type": "string" }
        }
      }
    }
  ],
  "signature": { "alg": "ES256", "kid": "prov_lux_hotels#1" }
}

Top-level fields

sgovrSpecVersion*
string
The spec version this document targets.
provider*
object
Identity and routing for the provider (see below).
mcp
object
MCP compatibility, e.g. compatible and a toolNamespace.
acceptedMandates
string[]
Mandate formats the provider accepts: sgovr-jwt (native) and/or ap2-vc (Agent Payments Protocol). Defaults to sgovr-jwt.
ap2
object
AP2 settings when accepting ap2-vc mandates: schemaVersion and merchantId.
actions*
array
One or more actions the provider exposes.
signature
object
Cryptographic signature over the spec, used for verification.

provider

id*
string
Stable identifier, e.g. prov_lux_hotels.
name*
string
Human-readable provider name.
did
string
Decentralized identifier used for domain verification.
homepage
string
Provider's public homepage.
adapterBaseUrl
string
Base URL the gateway calls to reach the provider's adapter (required to invoke the provider's actions).

actions[]

Each action describes a single callable operation.

name*
string
Action identifier, unique within the spec.
description*
string
What the action does - also used for discovery.
sideEffects*
"none" | "stateful" | "transactional"
none for read-only actions, stateful for non-financial side-effects, transactional for anything that moves money.
endpoint
object
HTTP method and path on the adapter.
pricing
object
Pricing model for the action (see below). Required for transactional actions.
auth
object
Required scopes. Mandatory for transactional actions.
rateLimit
object
Per-action limit, e.g. { "rpm": 30 }.
refundable
boolean
Whether settled transactions may be refunded.
ap2Sku
string
SKU the action maps to in an AP2 Cart mandate (when the provider accepts ap2-vc).
input*
JSON Schema
Schema for the action's request payload.
output*
JSON Schema
Schema for the action's response payload.

pricing

model*
"free" | "per_call" | "per_transaction"
How the action is priced.
takeRateBps
number
Sgovr's take-rate in basis points (e.g. 150 = 1.5%) for per_transaction actions.

auth

scopes*
string[]
Scopes the mandate must carry, e.g. booking:write, payments:charge.

Rules for transactional actions

  • They must declare both pricing and auth - a spec that omits either is rejected by validation.
  • At call time they require an idempotency key, so a retried request never settles twice.
  • The agent authorizes a spend amount, which the gateway reserves against the mandate cap before the call and captures on success.

The spec is the source of truth

Sgovr validates every spec against the schema, and the gateway enforces what the spec declares - scopes, pricing and limits. Validate yours with the SDK before registering it; see the TypeScript SDK guide.
PreviousMCP server