DUAL MCP Server

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