402ai-mcp

MCP (Model Context Protocol) server for 402ai.net - a Lightning-paid API proxy. Provides catalog-aware tools with compact/full profiles, bearer-first authentication, and dynamic tool refresh notifications.

Please update me when there are feature changes.

Features

• Two Tool Profiles: Compact (optimized for agents) or Full (comprehensive endpoint coverage)
• Catalog Synchronization: Auto-fetches and tracks API catalog changes
• Bearer Token Auth: First-class support for prepaid balance tokens
• Dynamic Tool Updates: Notifies clients when catalog changes via MCP notifications
• Smart Consolidation: Compact profile merges overlapping endpoints to reduce tool clutter
• TypeScript Native: Full TypeScript implementation with type safety
• Comprehensive Testing: Unit tests for catalog validation, deduplication, HTTP handling, and multipart uploads

Quick Start

Installation

npm install
npm run build
npm test

Run via stdio

ALBOM_BEARER_TOKEN=<your_token> npm start

NPM Package

npm install 402ai-mcp

Configuration

Configure via environment variables:

Variable	Default	Description
ALBOM_BASE_URL	https://402ai.net	API base URL
ALBOM_BEARER_TOKEN	(none)	Prepaid balance token (strongly recommended)
ALBOM_NWC_URI	(none)	Client-side NWC connection URI used to auto-pay topup invoices locally
ALBOM_NWC_THRESHOLD_SATS	1000	Trigger auto-topup when API responses report balance below this threshold
ALBOM_NWC_TOPUP_USD	2.00	USD amount to add for each automatic topup
ALBOM_NWC_MAX_DAILY	10.00	Max USD the MCP client will auto-top up over a rolling 24h window
ALBOM_TOOL_PROFILE	compact	Tool profile: compact or full
ALBOM_INCLUDE_MODERATION	false (compact), true (full)	Include moderation tools
ALBOM_INCLUDE_EMBEDDINGS	false (compact), true (full)	Include embedding tools
ALBOM_INCLUDE_VIDEO	true	Include video generation tools
ALBOM_ALLOW_RAW_TOOL	false	Expose albom_raw_call tool (full profile only)
ALBOM_CATALOG_TTL_MS	300000 (5 min)	Catalog cache TTL
ALBOM_HTTP_TIMEOUT_MS	90000 (90 sec)	HTTP request timeout
ALBOM_MAX_RETRIES	2	Max retry attempts for failed requests
ALBOM_MAX_UPLOAD_BYTES	26214400 (25 MB)	Max upload file size

Tool Profiles

Compact Profile (Default)

Optimized for AI agents with minimal tool ambiguity. Consolidates overlapping endpoints into semantic tools:

Tool	Purpose	Maps to Endpoint
albom_catalog_get	Get live API catalog	/api/v1/catalog
albom_text_generate	Generate text completions	/v1/responses
albom_image_generate	Generate images	/v1/images/generations
albom_image_edit	Edit images	/v1/images/edits
albom_audio_transcribe	Transcribe audio (with optional translation)	/v1/audio/transcriptions (+ /translations)
albom_audio_speech	Generate speech	/v1/audio/speech
albom_video_generate	Generate videos (if enabled)	/v1/video/generations
albom_safety_moderate	Content moderation (if enabled)	/v1/moderations
albom_embedding_create	Create embeddings (if enabled)	/v1/embeddings

Consolidations:

• Hides /v1/chat/completions in favor of /v1/responses (identical model sets)
• Folds /v1/audio/translations into albom_audio_transcribe via boolean flag

Full Profile

One tool per catalog endpoint for comprehensive coverage:

• albom_openai_chat_completions
• albom_openai_responses
• albom_openai_images_generations
• albom_openai_images_edits
• albom_openai_images_variations
• albom_openai_audio_speech
• albom_openai_audio_transcriptions
• albom_openai_audio_translations
• albom_openai_embeddings
• albom_openai_moderations
• albom_openai_video_generations
• albom_catalog_get
• albom_raw_call (if ALBOM_ALLOW_RAW_TOOL=true)

Authentication

Bearer Token (Recommended)

Set ALBOM_BEARER_TOKEN to your prepaid balance token. All requests will use Authorization: Bearer <token>.

Get a token:

# 1. Create topup invoice
curl -X POST https://402ai.net/api/v1/topup \
  -H "Content-Type: application/json" \
  -d '{"amount_sats":1000}'

# 2. Pay invoice with Lightning wallet, then claim
curl -X POST https://402ai.net/api/v1/topup/claim \
  -H "Content-Type: application/json" \
  -d '{"preimage":"<hex-preimage>"}'

NWC Auto-Topup

Set ALBOM_NWC_URI to a nostr+walletconnect://... URI to let the MCP client auto-pay topup invoices locally. The NWC secret stays in the MCP client process and is never sent to the 402ai server.

When a tool response includes balance_sats or available_sats below ALBOM_NWC_THRESHOLD_SATS, the MCP client will:

1. POST /api/v1/topup with {"amount_usd": ALBOM_NWC_TOPUP_USD}
2. Pay the returned invoice over NWC with pay_invoice
3. POST /api/v1/topup/claim with the returned preimage
4. Update the in-memory bearer token if the claim returns a newer token

Notes:

• Auto-topup is client-side only. The NWC URI never touches the 402ai server.
• ALBOM_NWC_MAX_DAILY is a rolling 24-hour USD spend cap for automatic topups.
• Auto-topup does not bootstrap a brand new account by itself. Start with a valid ALBOM_BEARER_TOKEN, then NWC can keep that balance funded.

No Token (L402 Flow)

Without a token, calls will return 402 Payment Required with a Lightning invoice. The MCP server will surface this as an error with payment details.

Usage Examples

With Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "402ai": {
      "command": "node",
      "args": ["/path/to/402ai-mcp/dist/server.js"],
      "env": {
        "ALBOM_BEARER_TOKEN": "abl_your_token_here",
        "ALBOM_NWC_URI": "nostr+walletconnect://...",
        "ALBOM_NWC_THRESHOLD_SATS": "1000",
        "ALBOM_NWC_TOPUP_USD": "2.00",
        "ALBOM_NWC_MAX_DAILY": "10.00",
        "ALBOM_TOOL_PROFILE": "compact"
      }
    }
  }
}

Programmatic Usage

import { createAlbomServer } from '402ai-mcp';

const server = createAlbomServer({
  baseUrl: 'https://402ai.net',
  bearerToken: process.env.ALBOM_BEARER_TOKEN,
  toolProfile: 'compact'
});

// Start server
await server.run();

Development

Build

npm run build

Documentation Discipline

Keep ARCHITECTURE.md and WORKLOG.md accurate when tool behavior, transport assumptions, auth flows, or deployment expectations change.

Test

npm test              # Run all tests
npm run test:watch    # Watch mode

Dev Server

npm run dev           # Watch and rebuild
npm run start:dev     # Run without build

Smoke Test (Live API)

ALBOM_BEARER_TOKEN=<token> npm run smoke:live

Architecture

Core Modules

• catalog.ts: Fetches and validates /api/v1/catalog, detects changes
• config.ts: Environment variable configuration and validation
• dedup.ts: Model set deduplication logic (Jaccard similarity)
• httpClient.ts: HTTP client with retry logic, multipart support, bearer auth
• tools/: Tool implementations for compact and full profiles
• results.ts: Response normalization and error handling
• uploads.ts: File upload handling (path and base64)
• server.ts: MCP server implementation

Catalog Sync

1. Fetches /api/v1/catalog on startup
2. Caches for ALBOM_CATALOG_TTL_MS
3. Periodically refreshes and compares
4. Sends notifications/tools/list_changed if catalog changes
5. Clients re-fetch tool definitions

Error Handling

HTTP errors are normalized to MCP-friendly format:

• 402 Payment Required: Returns payment details (invoice, amount, expires_in)
• 400 Bad Request: Returns validation errors
• 429 Rate Limited: Returns retry-after info
• 5xx Server Error: Returns error message
• Network errors: Automatic retry with exponential backoff

Testing

Test suite covers:

• Catalog validation and normalization
• Model set deduplication (Jaccard similarity)
• HTTP error normalization
• Multipart upload encoding (path + base64)
• Tool list change detection
• Bearer token authentication
• Retry logic

Run tests:

npm test

Publishing

# 1. Build and test
npm run build
npm test

# 2. Check package contents
npm pack --dry-run

# 3. Publish
npm login
npm version patch  # or minor/major
npm publish --access public

Project Structure

.
├── src/
│   ├── catalog.ts         # Catalog fetching and tracking
│   ├── config.ts          # Environment configuration
│   ├── dedup.ts           # Model set deduplication
│   ├── httpClient.ts      # HTTP client with retries
│   ├── server.ts          # MCP server implementation
│   ├── tools/             # Tool implementations
│   │   ├── compact.ts     # Compact profile tools
│   │   ├── full.ts        # Full profile tools
│   │   └── shared.ts      # Shared tool utilities
│   ├── results.ts         # Response normalization
│   ├── uploads.ts         # File upload handling
│   ├── types.ts           # TypeScript types
│   └── index.ts           # Public exports
├── test/                  # Test suite
├── scripts/               # Utility scripts
├── dist/                  # Compiled output
└── 402AI_MCP_IMPLEMENTATION_SPEC.md  # Design spec

Documentation:
└── 402AI_MCP_IMPLEMENTATION_SPEC.md

MCP Specification

This server implements MCP spec revision 2025-11-25.

Supported features:

• Tools capability
• Notifications capability (tools/list_changed)
• Tool annotations (title, readOnlyHint, idempotentHint)
• stdio transport

License

MIT - See LICENSE file.

Contributing

See WORKLOG.md for recent changes and development history.