> ## Documentation Index
> Fetch the complete documentation index at: https://shinydapps-bd9fa40b.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP Server
> Add l402-kit as an MCP tool so Claude Desktop, Cursor, and any MCP-compatible AI can pay Lightning APIs automatically.
## What is MCP?
[Model Context Protocol](https://modelcontextprotocol.io) is Anthropic's open standard for giving LLMs access to external tools. l402-kit ships a ready-made MCP server with two categories of tools:
### Generic L402 tools
| Tool | Description |
| ---------------------- | ---------------------------------------------------- |
| `l402_fetch` | Fetch any URL — pays automatically if it returns 402 |
| `l402_balance` | Check remaining Lightning budget |
| `l402_spending_report` | Full breakdown of payments this session |
### VERITY tools — paid services, auto-pay included
| Tool | Price | Description |
| --------------------- | ----------: | ------------------------------------------------- |
| `verity_btc_price` | 10 sats | Real-time BTC price in USD, EUR, BRL |
| `verity_worldstate` | 80 sats | UTC time + geolocation + local weather |
| `verity_search` | 100 sats | Web search, top 10 organic results |
| `verity_summarize` | 50 sats | AI summarization up to 50,000 chars |
| `verity_sentiment` | 30 sats | Sentiment score + keywords |
| `verity_scrape` | 200 sats | Web scraping to clean markdown |
| `verity_domain_intel` | 500 sats | WHOIS + DNS + SSL certificates |
| `verity_translate` | 50 sats | AI translation to 11 locales, MDX-aware |
| `verity_integration` | 10,000 sats | Complete l402-kit integration for any GitHub repo |
VERITY tools pay autonomously — no manual invoice handling needed.
***
## Setup in Claude Desktop
### 1. Install Node.js ≥ 18
### 2. Configure your wallet
Edit `claude_desktop_config.json`:
```json theme={null}
{
"mcpServers": {
"l402": {
"command": "npx",
"args": ["l402-kit-mcp"],
"env": {
"BLINK_API_KEY": "your-blink-api-key",
"BLINK_WALLET_ID": "your-wallet-id",
"BUDGET_SATS": "2000"
}
}
}
}
```
```json theme={null}
{
"mcpServers": {
"l402": {
"command": "npx",
"args": ["l402-kit-mcp"],
"env": {
"ALBY_TOKEN": "your-alby-access-token",
"BUDGET_SATS": "2000"
}
}
}
}
```
For a self-hosted Alby Hub, add:
```json theme={null}
"ALBY_HUB_URL": "https://your-hub.example.com"
```
**Config file location:**
* macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
* Windows: `%APPDATA%\Claude\claude_desktop_config.json`
### 3. Restart Claude Desktop
The tools `l402_fetch`, `l402_balance`, and `l402_spending_report` will appear in Claude's tool list.
***
## Environment variables
| Variable | Required | Description |
| ----------------- | :--------: | --------------------------------------- |
| `BLINK_API_KEY` | Blink only | Your Blink API key |
| `BLINK_WALLET_ID` | Blink only | Your Blink wallet ID |
| `ALBY_TOKEN` | Alby only | Alby access token |
| `ALBY_HUB_URL` | optional | Custom Alby Hub base URL |
| `BUDGET_SATS` | optional | Max spend per session (default: `2000`) |
***
## Using the tools
Once the server is running, Claude can call VERITY and any L402-protected API autonomously:
```
You: What's the BTC price right now?
Claude: [calls verity_btc_price]
[Paid 10 sats] {"bitcoin":{"usd":97500,"eur":89800,"brl":548000}}
Bitcoin is currently $97,500 USD (Cost: 10 sats)
```
```
You: Summarize this article:
Claude: [calls verity_summarize with text="..."]
[Paid 50 sats] {"summary":"..."}
```
```
You: Search for "lightning network adoption 2026"
Claude: [calls verity_search with q="lightning network adoption 2026"]
[Paid 100 sats] {"results":[...]}
```
```
You: How much have I spent so far?
Claude: [calls l402_spending_report]
=== L402 Spending Report ===
Total spent: 160 sats
Remaining: 1840 sats
By domain:
l402kit.com: 160 sats
```
***
## HTTP MCP endpoint
In addition to the stdio package, VERITY exposes a live **HTTP MCP server** — no installation required:
```
POST https://l402kit.com/api/mcp
Content-Type: application/json
```
Any MCP client that supports streamable HTTP transport can connect directly. Pass your Blink credentials as headers:
```
X-BLINK-API-KEY: your-blink-api-key
X-BLINK-WALLET-ID: your-wallet-id
```
**Initialize:**
```json theme={null}
{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}},"id":1}
```
**List tools:**
```json theme={null}
{"jsonrpc":"2.0","method":"tools/list","params":{},"id":2}
```
**Call a tool:**
```json theme={null}
{"jsonrpc":"2.0","method":"tools/call","params":{"name":"verity_btc_price","arguments":{}},"id":3}
```
The endpoint auto-pays Lightning invoices using your wallet credentials and returns the VERITY result directly.
***
## MCP registries
l402-kit is listed in all major MCP registries:
| Registry | Link |
| --------------------------------- | ---------------------------------------------------------------------------------------------- |
| Anthropic MCP Registry (official) | `io.github.ThiagoDataEngineer/l402-kit` |
| Glama | [glama.ai/mcp/servers/@ShinyDapps/l402-kit](https://glama.ai/mcp/servers/@ShinyDapps/l402-kit) |
| Smithery | [smithery.ai/servers/shinydapps/l402-kit](https://smithery.ai/servers/shinydapps/l402-kit) |
| mcp.so | search `l402-kit` |
Machine-readable manifest: `GET https://l402kit.com/.well-known/mcp.json`
***
## Setup with Cursor
Add the same config block to Cursor's MCP settings under **Settings → MCP Servers**.
***
## Setup with any MCP client
The server reads from `stdin` / writes to `stdout` (stdio transport):
```bash theme={null}
BLINK_API_KEY=xxx BLINK_WALLET_ID=yyy BUDGET_SATS=500 npx l402-kit-mcp
```
Any MCP-compatible client can connect using the stdio transport.
***
## Building a custom MCP server
You can also embed `L402Client` directly in your own MCP server:
```typescript theme={null}
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { L402Client, BlinkWallet } from "l402-kit";
import { z } from "zod";
const client = new L402Client({
wallet: new BlinkWallet(process.env.BLINK_API_KEY!, process.env.BLINK_WALLET_ID!),
budgetSats: 1000,
});
const server = new McpServer({ name: "my-agent", version: "1.0.0" });
server.tool(
"fetch_weather",
"Get current weather for a city — pays automatically",
{ city: z.string() },
async ({ city }) => {
const res = await client.fetch(`https://api.weather.com/current?city=${city}`);
const text = await res.text();
return { content: [{ type: "text", text }] };
},
);
const transport = new StdioServerTransport();
await server.connect(transport);
```
***
## Security notes
* The budget cap (`BUDGET_SATS`) is your primary safeguard — set it conservatively
* Each `npx l402-kit-mcp` process has its own in-memory budget; it resets on restart
* For production agents, persist the spending log via `onSpend` callback to an external store