An agent that takes tools pays through Alba's MCP server. The server ships inside @alba/sdk as the command alba-mcp. It speaks MCP over stdio, holds one grant credential, and gives the agent two tools.
Add the server to a client#
Most MCP clients take a server as a command, its arguments and its environment. This entry starts alba-mcp with a grant:
{
"mcpServers": {
"alba": {
"command": "npx",
"args": ["-y", "--package", "@alba/sdk", "alba-mcp"],
"env": {
"ALBA_GRANT": "alba_grant_…"
}
}
}
}ALBA_GRANT is the grant credential from the app. The server needs Node 22 or later. The credential stays in the server's process: no tool returns it, and the model never sees it.
Create the grant first with Give an agent a grant. A grant used by an MCP server should be used by that server alone.
The tools#
fetch_paid#
Fetches a URL and pays for it from the grant when the seller answers 402. It is alba.fetch as a tool.
| Input | Type | Meaning |
|---|---|---|
urlrequired | string | The URL to fetch. |
method | string | The HTTP method. GET when left out. |
headers | Record<string, string> | Request headers. |
body | string | The request body. |
The result is one text item holding JSON:
| Result | Type | Meaning |
|---|---|---|
status | number | The HTTP status of the final response. |
headers | Record<string, string> | Its headers. A paid response has payment-response. |
body | string | Its body as text. |
A request to a URL that asks for no payment comes back as it is and spends nothing. When the grant does not allow a payment, the tool call fails with the reason: the price is over the cap, the seller is not on the list, the grant is expired, revoked or short. Pay x402 from an agent lists each one.
grant_status#
Takes no input and spends nothing. The result is one text item holding the grant as JSON:
| Result | Type | Meaning |
|---|---|---|
remaining | string | What the grant has left, in raw units. |
spent | string | What it has paid to sellers. |
feesPaid | string | What it has paid in fees. |
startingAmount | string | What it held when created. |
granted | string | Everything put into the grant: the starting amount plus every top-up. |
terms | { cap, expiry, sellers } | The cap per payment, the expiry in Unix seconds, and the seller list. |
state | string | active, expired, spent or revoked. |
mint | string | The asset's mint. |
An agent can call it before a costly request to see whether the grant covers it.
Start the server from your own code#
To embed the server in a Node program, or to pass the credential without the environment:
import { startMcpServer } from '@alba/sdk/mcp'
await startMcpServer({ credential })startMcpServer connects to stdio and resolves once the server is listening. Without credential it reads ALBA_GRANT. It also accepts facilitatorUrl, fetch and artifactBaseUrl, the same transport options as alba.with, and applies them either way.
What the owner sees#
Every fetch_paid that pays makes a row in the grant's ledger, with the method and URL the tool was called with as its memo. The owner reads them in the app and tops the grant up or revokes it there.