DUAL MCP Server

AI-native integration with the DUAL tokenization platform via the Model Context Protocol.

This MCP server enables AI agents to interact directly with the DUAL Web3 Operating System — minting tokens, managing templates, executing actions, deploying webhooks, and querying blockchain infrastructure. Not through screen scraping or API wrappers, but through native integration that treats AI agents as first-class users of the system.

Features

• 115 tools across 17 API modules

• Full CRUD for wallets, organizations, templates, objects, faces, webhooks, notifications, and API keys

• Event Bus — execute actions and batch operations atomically

• Sequencer & ZK-Rollup — query batches and checkpoints

• AI Services — intelligence (agents, predictions, knowledge graph), governance (compliance, provenance), creative (token design, face templates)

• Public API — read-only access without authentication

• Dual transport — stdio for local use, HTTP for remote deployment

• Session-isolated HTTP — each HTTP request gets its own auth context

Quick Start

Install

npm install
npm run build

Configure

Set your authentication via environment variables:

# Option 1: API Key (recommended for server-to-server)
export DUAL_API_KEY=your-api-key

# Option 2: JWT Token
export DUAL_ACCESS_TOKEN=your-jwt-token

# Option 3: Use the dual_login tool interactively (stdio mode only — see note below)

Note on dual_login and HTTP mode: HTTP mode is stateless — each request creates a fresh server and API client, so any auth state set by dual_login is discarded after that single request. For HTTP deployments, always supply credentials via environment variable (DUAL_API_KEY or DUAL_ACCESS_TOKEN) rather than calling dual_login interactively. Interactive login via dual_login only works reliably in stdio mode.

Run

# stdio transport (for Claude, Cursor, etc.)
node dist/index.js

# HTTP transport (for remote/multi-client)
# MCP_SERVER_API_KEY is REQUIRED for HTTP mode
MCP_SERVER_API_KEY=your-secret TRANSPORT=http PORT=3100 node dist/index.js

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "dual": {
      "command": "node",
      "args": ["/path/to/dual-mcp-server/dist/index.js"],
      "env": {
        "DUAL_API_KEY": "your-api-key"
      }
    }
  }
}

API Modules & Tools

Core DUAL API (81 tools)

AI Services (34 tools)

These tools require the DUAL AI microservices running alongside the server. See AI Service Dependencies below.

Example Usage

Natural Language → Token Deployment

"Create a redeemable reward token for my brand with 1 million supply, set up a rule that expires after 12 months, and mint it on Base."

The AI agent uses:

1. dual_create_template — define the reward token structure

2. dual_create_action_type — register "Redeem" and "Expire" actions

3. dual_execute_action — mint the initial supply

4. dual_create_webhook — set up expiry monitoring

Querying Infrastructure

"Show me the latest ZK checkpoint and how many objects are on the platform."

1. dual_list_checkpoints — latest rollup state

2. dual_public_get_stats — platform-wide statistics

Environment Variables

AI Service Dependencies

The intelligence, governance, and creative tool modules connect to separate DUAL AI microservices. If these services are not running, those 34 tools will return connection errors; the remaining 81 core tools are unaffected.

Architecture

dual-mcp-server/
├── src/
│   ├── index.ts              # Server factory, transport setup (stdio + HTTP)
│   ├── constants.ts          # API URL, limits, MCP_SERVER_API_KEY
│   ├── schemas/
│   │   └── common.ts         # Shared Zod schemas (pagination, IDs, filters)
│   ├── services/
│   │   ├── api-client.ts     # ApiClient class (per-session auth + HTTP requests)
│   │   ├── ai-client.ts      # HTTP client for AI microservices
│   │   ├── security.ts       # SSRF, NoSQL injection, input validation
│   │   └── formatters.ts     # Response formatting, truncation
│   └── tools/
│       ├── wallets.ts        # 11 wallet tools (incl. login, logout)
│       ├── organizations.ts  # 10 organization tools
│       ├── templates.ts      # 7 template tools
│       ├── objects.ts        # 8 object tools
│       ├── actions.ts        # 7 event bus tools
│       ├── faces.ts          # 6 face tools
│       ├── storage.ts        # 4 storage tools
│       ├── webhooks.ts       # 6 webhook tools
│       ├── notifications.ts  # 5 notification tools
│       ├── sequencer.ts      # 4 sequencer tools
│       ├── api-keys.ts       # 3 API key tools
│       ├── payments.ts       # 2 payment tools
│       ├── support.ts        # 3 support tools
│       ├── public-api.ts     # 5 public API tools
│       ├── intelligence.ts   # 12 intelligence tools
│       ├── governance.ts     # 14 governance tools
│       └── creative.ts       # 8 creative tools
├── SECURITY.md               # Security policy & reporting
└── dist/                     # Compiled JavaScript

Security

See SECURITY.md for the security policy, threat model, and how to report vulnerabilities.

Key security features:

• Session isolation: HTTP mode creates a fresh server + auth context per request

• SSRF protection: External URL validation blocks private networks and cloud metadata

• NoSQL injection prevention: Filter schemas reject $-operator keys

• Input validation: Zod schemas with size/depth limits on all tool inputs

• Rate limiting: Per-IP rate limiting with configurable max

• Security headers: X-Content-Type-Options, CSP, HSTS, X-Frame-Options

License

MIT