> ## Documentation Index
> Fetch the complete documentation index at: https://tanso.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Operate your billing with an AI agent — same auth, same scoping, no separate path

Tanso ships a built-in [MCP](https://modelcontextprotocol.io) server so AI
agents can operate your instance directly. It authenticates with the same API
keys as everything else and is scoped to the key's account — an agent gets no
separate, weaker path.

It's **off by default**. Enable it with two flags and restart:

```bash theme={null}
APP_MCP_ENABLED=true
SPRING_AI_MCP_SERVER_ENABLED=true
```

The tenant-configuration tools (`Admin*` — plans, rules, credit tariffs and
prices — plus Stripe setup) require a third, separate opt-in:

```bash theme={null}
APP_MCP_ADMIN_TOOLS_ENABLED=true
```

Leave it off unless every holder of a client API key is the operator. This
gate is what lets you hand an MCP endpoint to an end customer's agent: with
it off, a customer-scoped (`ck_`) key reaches only the curated customer
tools — `listPlans`, `getCreditPrices`, `checkEntitlement`,
`getUsageForecast`, `subscribePlan`, `purchaseCredits` (spend tools require
`confirmAction: true`) — pinned to its own customer. See
[Agent-serve](/agent-serve).

Then connect any MCP client to `/mcp`:

```bash theme={null}
claude mcp add tanso --transport http \
  --header "X-API-Key: sk_test_your_key" \
  http://localhost:8080/mcp
```

## What you'd actually use it for

**Billing ops from a chat window.** Connect Claude Desktop to your instance
and ask questions that would otherwise mean writing queries: *"Which
customers are near their usage caps?"* — *"Show cust\_demo\_1's credit
transactions this month"* — *"Mark invoice X paid."* No code, no dashboard
tab.

**Customer support with receipts.** The credit ledger records
`balance_before`/`balance_after` on every transaction, so an agent answering
"where did my credits go?" can cite the exact entries.

**Catalog work by conversation.** The admin tools cover features, plans,
pricing rules, and credit models — an agent can draft a new plan's rule
configuration and you review it in the dashboard.

## Guardrails

Tools that spend money or make hard-to-reverse changes require an explicit
`confirmAction: true` argument — the tool refuses with an explanation until
the agent passes it. Generating AI insights (costs model tokens), Stripe
setup, subscription cancellation, and credit grants/deductions are gated this
way. Destructive tools also say so in their descriptions (`DESTRUCTIVE:`,
`SIDE EFFECT:`) so agents can reason about them before calling.

## Known rough edge

`ingestEvent` currently requires `occurredAt` (ISO-8601), unlike the REST
API, which defaults it to now — and omitting it yields an unhelpful error
(`{"error": "ingestion_failed", "message": "text"}`). Until that's fixed,
always pass `occurredAt` explicitly when ingesting events over MCP.

## The design stance

An agent operating your billing uses the same authenticated, account-scoped
surface as your code — 62 tools mirroring the client and admin APIs. Nothing
is agent-only, and nothing is weaker because an agent is calling it. If you
wouldn't expose an operation to a human with that API key, it isn't exposed
to an agent either.