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_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>"}'

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_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

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.