# Tanso Agent Integration Guide

## What Tanso Is

Tanso is the open-source (AGPL-3.0) engine that lets AI agents sign up, pay
for, and use a B2B product. For operators it is a monetization engine:
billing, usage metering, real-time entitlements, the credit wallet (prepaid pools with grants, expiry, rollover), server-side credit pricing (a versioned weight tariff for credits-per-action and a price book for price-per-credit), and
per-customer margin in one ledger. It is self-hosted; there is no hosted
API at tansohq.com.

- Source: https://github.com/tansohq/tanso-oss
- Docs: https://tanso.mintlify.app
- SDK: https://www.npmjs.com/package/@tansohq/sdk
- Pricing (machine-readable): https://tansohq.com/pricing.json

## MCP

Every Tanso instance ships an MCP server at `/mcp` (off by default; one config
flag enables it, a second enables the admin tools). Connect your agent to the
instance you're working with:

```json
{
  "mcpServers": {
    "tanso": {
      "url": "https://YOUR-INSTANCE/mcp",
      "headers": {
        "X-API-Key": "sk_test_your_key"
      }
    }
  }
}
```

Auth and scoping are identical to the REST API: an agent gets no separate,
weaker path. Tools that spend money or make hard-to-reverse changes require
an explicit `confirmAction: true` argument.

Setup and the full tool catalog: https://tanso.mintlify.app/mcp

## Agent-serve (for your customers' agents)

A Tanso-powered product can serve its END CUSTOMERS' buying agents, opt-in
per account:

- Machine-readable pricing at /public/v1/catalog/{slug}/pricing.json
  (agent-serve pricing.json schema). One GET, no auth, nothing to scrape.
- Programmatic signup: POST /public/v1/catalog/{slug}/signup returns a
  customer, a free-plan subscription, and a customer-scoped API key in one
  call. No CAPTCHA, no email loop.
- Customer-scoped keys (ck_...) pinned to one customer with read/purchase
  scopes; deny-by-default everywhere else.
- Payments without a browser: SetupIntent pre-authorization, off-session
  subscribe and credit top-ups; HTTP 402 + pollable checkout session when
  no card is on file; per-account agent spend caps.
- Burndown API: per-feature projections and credit depletion dates; stable
  error codes; Idempotency-Key replay on mutating requests.

## REST integration loop

1. `GET /api/v1/client/entitlements/{customerReferenceId}/{featureKey}` to check before serving
2. Serve the request
3. `POST /api/v1/client/events` to report usage (idempotent via `eventIdempotencyKey`)

Full walkthrough: https://tanso.mintlify.app/billing-lifecycle

More for agents: https://tansohq.com/llms.txt