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:

Tool Profiles

Compact Profile (Default)

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

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.