Guides

Use Alba from an MCP client

The alba-mcp server and its two tools, for agents that take tools.

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:

json
{
  "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.

InputTypeMeaning
urlrequiredstringThe URL to fetch.
methodstringThe HTTP method. GET when left out.
headersRecord<string, string>Request headers.
bodystringThe request body.

The result is one text item holding JSON:

ResultTypeMeaning
statusnumberThe HTTP status of the final response.
headersRecord<string, string>Its headers. A paid response has payment-response.
bodystringIts 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:

ResultTypeMeaning
remainingstringWhat the grant has left, in raw units.
spentstringWhat it has paid to sellers.
feesPaidstringWhat it has paid in fees.
startingAmountstringWhat it held when created.
grantedstringEverything 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.
statestringactive, expired, spent or revoked.
mintstringThe 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:

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