Lightning Enable MCP Server

Part of Lightning Enable — infrastructure for agent commerce over Lightning.

Lightning Enable MCP Server

[Discord] [PyPI downloads] [NuGet downloads] [Docker pulls]

Monetize your own API — 30-day free trial

Agents pay your API per request over Lightning — flat subscription at $49/mo, and you keep 100% of every sat.

• Start free trial — 30 days, no charge today
• Fast Lane — pay 100 sats over Lightning, no card
• Pricing

Or sign up without leaving your agent: call the create_lightning_enable_account tool.

An open-source MCP (Model Context Protocol) server that enables AI agents to make Lightning Network payments and participate in agent-to-agent commerce. Wallet, invoice, L402, budget, and API-discovery tools work out of the box with just a wallet. Producer tools (sell access via L402) and Agent Service Agreement (ASA) tools (agent-to-agent discovery, request, settlement, and attestation over Nostr) unlock with an Agentic Commerce subscription. See the full tool list.

Available in .NET and Python.

What It Does

Give your AI agent a Lightning wallet and it can:

• Pay invoices — Send Bitcoin via Lightning to any BOLT11 invoice
• Access L402 APIs — Automatically pay L402 challenges for seamless API access
• Discover APIs — Search the L402 API registry to find paid APIs by keyword or category, or fetch a specific API's manifest for full endpoint details and pricing
• Track spending — Budget limits, a durable receipt log, and balance checks
• Create invoices — Generate invoices to receive payments
• Run wallet operations — BTC price, currency exchange, and on-chain sends (Strike; on-chain also LND)
• Self-bootstrap a Lightning Enable account — create_lightning_enable_account pays a ~100-sat activation fee over L402 and returns a merchant API key: the free→paid signup form that is the protocol, unlocking the producer + ASA tools with no browser or checkout page.
• Sell services (L402 Producer) — Set up the seller account, put an API behind L402, price its routes, list it publicly, mint payment challenges and verify payer tokens — all from one tool, so an agent can go from an API key to a paid endpoint without touching REST
• Agent commerce (ASA) — Discover, request, settle, and review agent-to-agent services on Nostr

Quick Start

1. Install

# .NETdotnet tool install -g LightningEnable.Mcp
# Pythonpip install lightning-enable-mcp
# Python (no install)uvx lightning-enable-mcp
# Dockerdocker pull refinedelement/lightning-enable-mcp:latest

2. First run — setup_wallet

Nothing else works without a wallet, so start there. Ask your agent:

Run setup_wallet

With no arguments it reports which wallet is configured and where the credential came from — the provider and the source, never the credential itself. If there is no wallet, it hands back the setup steps.

The shortest path is NWC. In your wallet app (Alby Hub, CoinOS, or any NIP-47 wallet) create a Nostr Wallet Connect connection, copy the nostr+walletconnect:// string, and give it to the agent:

Run setup_wallet with this connection string: nostr+walletconnect://...

setup_wallet validates the string, connects to the wallet to prove it answers, then writes it to ~/.lightning-enable/config.json with the file's permissions restricted to your user. It reports the wallet's declared methods and balance. Restart the server afterwards so it picks up the new wallet.

Or set an environment variable (in the Claude Desktop config below, say). L402 — the whole point of this server — needs a wallet that returns the payment preimage:

• Strike — STRIKE_API_KEY, from https://dashboard.strike.me
• NWC — NWC_CONNECTION_STRING, from CoinOS / CLINK / Alby Hub
• LND (your own node — always returns a preimage) — LND_REST_HOST + LND_MACAROON_HEX
  • Self-signed node cert? Set LND_TLS_CERT_PATH to the node's tls.cert (pins TLS to that cert). LND_SKIP_TLS_VERIFY=true is the escape hatch, not the recommendation. Optional: LND_FEE_LIMIT_SATS, LND_PAYMENT_TIMEOUT_SECONDS.

⚠️ OpenNode (OPENNODE_API_KEY) works for invoicing / direct payments only — it never returns a preimage, so it cannot pay L402 challenges. Don't make it your only wallet if you want L402 (the core use case).

If several are set, priority is: LND > NWC > Strike > OpenNode, and environment variables win over the config file — setup_wallet refuses to write a connection string that an env var would override, and tells you which variable to unset. See Supported Wallets for the full compatibility matrix.

3. Prove the whole loop works — test_l402_payment

Ask your agent:

Run test_l402_payment

This pays a public 1-sat L402 endpoint end to end, proving your wallet is connected, returns a preimage, and can complete a real L402 payment. It's the one-line answer to "is my wallet actually working?" — and it costs about 1 satoshi.

4. Then have some fun — buy a t-shirt

Once the loop works, try the Lightning Enable Store, a live L402-powered web store. Ask Claude:

Buy me a Lightning Enable t-shirt from store.lightningenable.com

(This one needs a funded wallet and a shipping address, which is why test_l402_payment — one sat, no shipping — is the faster first proof.)

Claude Desktop manual install (MCPB bundle)

For a one-click install with no config-file editing, grab the packaged MCPB bundle from the mcpb/ directory instead of hand-editing JSON: build it locally with npx -y @anthropic-ai/mcpb pack mcpb lightning-enable-mcp.mcpb (or download the .mcpb artifact from a mcpb.yml CI run), then double-click the resulting .mcpb file or drag it into Claude Desktop's Settings → Extensions — Claude Desktop prompts for your wallet credentials (Strike, NWC, or LND) and optional Lightning Enable API key through its own settings UI instead of a text config file. See mcpb/README.md for what's in the bundle and mcpb/SUBMISSION.md for its Anthropic MCP Directory submission status.

Claude Desktop Config

Add to your claude_desktop_config.json:

.NET:

{  "mcpServers": {    "lightning-enable": {      "command": "lightning-enable-mcp",      "env": {        "STRIKE_API_KEY": "your-strike-api-key"      }    }  }}

dotnet tool install -g LightningEnable.Mcp puts the lightning-enable-mcp command on your PATH. If Claude Desktop can't find it, set command to the full path: "C:\\Users\\<you>\\.dotnet\\tools\\lightning-enable-mcp.exe" on Windows (JSON needs the doubled backslashes), /Users/<you>/.dotnet/tools/lightning-enable-mcp on macOS, or /home/<you>/.dotnet/tools/lightning-enable-mcp on Linux. The config file doesn't expand environment variables such as %USERPROFILE% or $HOME.

Python:

{  "mcpServers": {    "lightning-enable": {      "command": "uvx",      "args": ["lightning-enable-mcp"],      "env": {        "STRIKE_API_KEY": "your-strike-api-key"      }    }  }}

Config file locations:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/claude/claude_desktop_config.json

Deploying hosted

A payment above your auto-approve threshold needs a human's approval: the server mints a short confirmation code, sends it to you, and the agent can only proceed once you read it back. The code never appears in a tool result, so a prompt-injected agent can't approve its own spending by reading the result.

Treat this as an operator confirmation aid on a trusted local host, not as an independent approval boundary: if the agent's host can read the server's console, log stream, approval file, or webhook destination, it can read the code too.

That only works if the code reaches a human. On your laptop it goes to the server's console (stderr) and you read it there. On a hosted server — a claude.ai connector, a Docker container, a fleet — nobody is watching stderr, and on a shared host the agent might read it itself. So you choose the approval channel.

Whatever the channel, two rules hold: the code is never returned to the agent, and a payment is never approved because its notification failed to send — a delivery failure refuses the payment and withdraws the code.

Codes are 6 characters, one-time use, and bound to the exact amount, tool, and destination. At most 3 codes can be outstanding at once, and 5 invalid code attempts in a row revoke every pending code. A code lives 120 seconds by default; set confirmation.ttlSeconds (or LIGHTNING_ENABLE_CONFIRMATION_TTL_SECONDS) to change it, clamped to 30-900. For the asynchronous webhook and file channels, 300-600 is a practical value.

Choosing a channel

Precedence: environment variable, then config file, then automatic.

{  "confirmation": {    "channel": "webhook",    "webhookUrl": "https://ops.example.com/lightning-approvals",    "webhookSecret": "<shared secret>",    "filePath": "/var/log/lightning-enable/confirmations.jsonl",    "ttlSeconds": 600  }}

With no channel set, the server decides:

An stdio MCP server always has a piped stdin, so the warning is a nudge, not a diagnosis: if a human really is watching the console, ignore it. LIGHTNING_ENABLE_HOSTED=1 is the explicit opt-in that turns the safe posture on — nothing flips your behavior automatically.

A channel name the server can't parse fails closed to refuse and says so at startup, so a typo never silently restores a code nobody reads.

The webhook payload

POST with Content-Type: application/json and an HMAC-SHA256 signature over {timestamp}.{body}, the same scheme the Lightning Enable API signs merchant webhooks with:

X-LightningEnable-Signature: t=1757203200,v1=9f86d081...

{  "type": "payment.confirmation_required",  "nonce": "AB12CD",  "tool": "pay_invoice",  "amountSats": 50000,  "amountUsd": 12.34,  "destination": "lnbc500u1pj9npjpp5abcdefghijklmnopqr...",  "description": "lnbc500u1pj9npjpp5...",  "summary": "pay_invoice — $12.34 (50,000 sats), invoice lnbc500u1pj9npjpp5...",  "createdAt": "2026-09-07T12:00:00Z",  "expiresAt": "2026-09-07T12:02:00Z",  "expiresInSeconds": 120}

The file channel writes this exact object, one JSON line per confirmation, and pins the file to 0600 on POSIX — it holds live approval codes.

Two things to know about the webhook:

• The URL must be public. It goes through the same connect-time SSRF guard as agent-supplied URLs, so a private, loopback, or metadata address is refused at startup.
• Redirects are never followed. A 3xx answer is a delivery failure, so a signed approval only ever reaches the URL you configured.

Codes expire after 120 seconds and are bound to the exact amount, tool, and destination they were approved for.

Supported Wallets

Spending limits

Limits live in ~/.lightning-enable/config.json and are read-only at runtime — an agent can tighten its own caps but never raise them. You can set them in USD, in satoshis, or both.

{  "limits": {    "maxPerPayment": 500.00,    "maxPerSession": 100.00,    "maxPerPaymentSats": 5000,    "maxPerSessionSats": 50000,    "autoApproveSats": 100  }}

Defaults. On first run both ports write the same file: approval tiers autoApprove $0.10, logAndApprove $1.00, formConfirm $10.00 and urlConfirm $100.00; maxPerPayment $500.00 and maxPerSession $100.00; requireApprovalForFirstPayment: true; cooldownSeconds 2. A key you leave out of an existing file takes the same default.

An omitted USD limit is not "no limit". If you set only the sats limits, maxPerPayment and maxPerSession still apply at $500.00 and $100.00. To rely on the sats limits alone, set the USD keys to null:

{ "limits": { "maxPerPayment": null, "maxPerSession": null, "maxPerSessionSats": 50000 } }

Tiers must ascend. If a tier is above the tier over it, it is lowered to that tier's value, never raised: {"tiers": {"autoApprove": 2}} with the default logAndApprove of $1.00 auto-approves up to $1.00, not $2.00. Set the tiers above it too to raise it.

Why set the sats ones. A USD limit has to be converted at the current BTC price, so when every price source is down the payment cannot be checked and is refused — correct, but it stops the agent. A satoshi limit needs no conversion, so a sats-budgeted agent keeps working through a price outage. Set both maxPer…Sats keys to close every gap.

When both denominations are set, the stricter cap wins on every check. budget(action="status") reports which one is binding (bindingDenomination), the effective cap in sats, whether a price was available, and whether outage mode is active.

What happens during a price outage

The satoshi ceilings still bound the spend. But a ceiling says "never more than this" — it does not say "this much is fine unattended", and the USD tier ladder that normally says the second thing cannot be evaluated without a price. So approval fails closed:

• autoApproveSats set — payments at or below it are auto-approved; anything above takes the normal confirmation flow (the agent asks the human for the code printed to the server console).
• autoApproveSats not set — every payment needs confirmation until a price source recovers.

autoApproveSats is a tier, not a ceiling: it can never widen maxPerPaymentSats or maxPerSessionSats, which are checked first. It is ignored entirely while a price is available — then the USD tiers decide as usual.

The auto-pay paths (L402 auto-payment, send_onchain, agent_services action=settle) refuse anything that needs confirmation rather than prompting. During an outage that means they only proceed under autoApproveSats.

Tools

Canonical inventory: the table below. Tools marked Free work out of the box with just a wallet (docs needs nothing at all); tools marked Agentic Commerce require LIGHTNING_ENABLE_API_KEY (an Agentic Commerce subscription). The table is pinned to the code by the tool-inventory guard tests in both ports (ToolInventoryTests.cs, test_server.py), so drift fails CI; quote counts from those tests, never from prose.

Some of these are action tools: pass action (or source for receipts) to pick the operation. All but docs replace a family of single-purpose tools whose schemas used to be loaded into the agent's context on every session — see Tool profiles and old tool names. Every old name still works.

ASA availability note. Against the hosted Lightning Enable API, agent_services actions discover, request, settle, publish, unpublish, and reputation work. attest is refused, because the hosted API has no route that accepts attestations, so you can't leave a review through it. See Agent Service Agreements.

create_lightning_enable_account is free and self-provisions the API key the Agentic Commerce tools need — an agent with a wallet pays a ~100-sat activation fee and unlocks them on the spot.

docs reads llms-full.txt, the whole docs site in one file, and keeps it in memory for an hour. If a refresh fails it serves the cached copy and marks the result stale. Set LIGHTNING_ENABLE_DOCS_URL to read another copy (https://, http:// on localhost, or a local file:// path; network shares are refused). Redirects are not followed: point the variable at the final URL.

Every tool carries MCP annotations: a human-readable title and an explicit readOnlyHint, plus destructiveHint on anything that can spend the wallet. Action tools are annotated for their widest action, so budget is not read-only (because tighten writes) and wallet_ops is destructive (because send_onchain is).

Resources

The durable receipt log is also exposed as MCP resources, so a client can attach or display it without the model spending a turn on a tool call:

Both read through the same path as the receipts tool, which redacts credential-shaped fields at the read boundary — a preimage never leaves the process. The payment hash is the safe reference; the preimage is the proof of payment and is not a receipt field. Resources are unaffected by the tool profile: they cost no schema bytes in the model's context.

Tool profiles and old tool names

Every advertised tool's JSON schema is loaded into the agent's context at the start of each session, so the tool surface is a token cost on every turn. Pick how much of it to advertise with LIGHTNING_ENABLE_TOOL_PROFILE:

{  "mcpServers": {    "lightning-enable": {      "command": "uvx",      "args": ["lightning-enable-mcp"],      "env": {        "STRIKE_API_KEY": "your-strike-api-key",        "LIGHTNING_ENABLE_TOOL_PROFILE": "lite"      }    }  }}

Profiles are listing-only. A tool the profile does not advertise is still callable by name, and every old name still dispatches, under every profile. Narrowing the profile trims the schemas pushed into the model's context; it never removes capability.

Old name → new call

Old names are accepted but unadvertised (except under full). Each forwards to the new tool and its result carries a deprecated marker naming the replacement. Removed in v3.0.0 — move to the new names.

The last three predate this consolidation and stay hidden in every profile, full included.

Documentation

• .NET README — Full .NET documentation
• Python README — Full Python documentation
• Full Docs — Complete guide to every tool
• AI Spending Security — Budget controls and safety

Repository Structure

lightning-enable-mcp/├── dotnet/│   ├── src/LightningEnable.Mcp/         # .NET MCP server│   ├── tests/LightningEnable.Mcp.Tests/  # .NET tests│   └── LightningEnable.Mcp.sln          # Solution file├── python/│   └── lightning-enable-mcp/             # Python MCP server├── .github/workflows/publish-mcp.yml     # CI/CD├── LICENSE                               # MIT└── README.md                             # This file

Selling with L402 (the l402_producer tool)

The whole seller side behind one tool. Pass action to pick the operation. Every action needs LIGHTNING_ENABLE_API_KEY (an Agentic Commerce subscription); no action can spend your wallet.

API version. create, verify, create_proxy, add_endpoint and publish work against every Lightning Enable API build. configure_receive needs the NWC receiving lane and list_challenges needs the challenge-listing route, both of which ship with the API release this version targets. Run l402_producer(action="status") first — it degrades gracefully and tells you what the deployment you are pointed at supports.

From an API key to a paid endpoint

No dashboard, no REST client, no human in the loop. Each step is one tool call:

1. Get an API key. create_lightning_enable_account — pays a ~100-sat activation fee from your wallet and writes the key to ~/.lightning-enable/config.json. Restart the server so the gated tools unlock. (Skip if you already have a key.)
2. Point payouts at your own wallet. l402_producer(action="configure_receive") — with no argument it reuses the NWC wallet this server already pays with; pass nwc_connection_string to use a different one. The string is never echoed back, only <set>.
3. Check where you stand. l402_producer(action="status") — plan, receiving wallet, and the onboarding checklist, so the agent can see what is still missing.
4. Put your API behind L402. l402_producer(action="create_proxy", name="Weather API", target_base_url="https://api.example.com", default_price_sats=25) — returns a proxy_id and the public base URL. Every request under it now answers 402 until it is paid.
5. Price each route. l402_producer(action="add_endpoint", proxy_id="weather-api", endpoint_id="forecast", path="/forecast", http_method="GET", price_sats=10) — repeat per route.
6. List it. l402_producer(action="publish", proxy_id="weather-api", service_description="Five-day forecasts for agents", categories=["weather"]) — returns the OpenAPI and manifest URLs. Other agents find it through discover_api.
7. Watch the money arrive. l402_producer(action="list_challenges", challenge_status="paid") — payment hash, resource, amount and status. Never a macaroon, never a preimage.

For a resource you are not proxying — a file, a report, a one-off answer — skip steps 4-6 and use create / verify directly.

Payouts settle on your wallet. Lightning Enable does not hold the funds.

Agent Service Agreements (the agent_services tool)

Agent-to-agent commerce on Nostr, behind one tool. Pass action to pick the operation. agent_services requires LIGHTNING_ENABLE_API_KEY (an Agentic Commerce subscription); action="settle" additionally spends your wallet balance, subject to budget limits.

The hosted Lightning Enable API refuses attest, because it has no route that accepts attestations, so you can't leave a review through it; discover, request, settle, publish, unpublish, and reputation work.

How Agent Commerce Works

1. Discover — agent_services(action="discover", category="translation") finds agents offering translation
2. Request — agent_services(action="request", capability_event_id=..., budget_sats=100) sends a service request
3. Settle — agent_services(action="settle", l402_endpoint=...) pays via Lightning and receives the result
4. Review — agent_services(action="attest", subject_pubkey=..., agreement_id=..., rating=5) builds on-protocol reputation (the hosted API refuses this action)

For dynamic pricing, providers use l402_producer(action="create") to generate invoices at the agreed price. Requesters pay and providers verify with l402_producer(action="verify").

The seven old tool names (discover_agent_services, settle_agent_service, …) still work — see Old name → new call.

Related Projects

• le-agent-sdk (Python) — pip install le-agent-sdk
• le-agent-sdk (TypeScript) — npm install le-agent-sdk
• le-agent-sdk (.NET) — dotnet add package LightningEnable.AgentSdk

Privacy

Lightning Enable does not hold funds — the connected wallet or payment provider (Strike, OpenNode, LND, or an NWC wallet) does. The MCP server runs locally and talks to the wallet/provider you configure and, for L402 discovery, the L402 API registry. Wallet credentials you supply stay on your machine (or, for the hosted API, are encrypted at rest). See the full Privacy Policy for what data is collected, third parties involved, retention, and contact ([email protected]).

Support

If something's broken or not working, email [email protected] — a real person reads it. For general questions, join the Discord: https://discord.gg/rX7NxHY8vx. Bug reports and feature requests: open an issue on this repo.

License

MIT — see LICENSE.

Links

• Lightning Enable — Payment enablement middleware
• Documentation — Full docs
• Store — Live L402 demo
• NuGet — .NET package
• PyPI — Python package
• Docker Hub — Docker image