DUAL 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)

Module	Tools	Description
Wallets	11	Authentication, registration, profile management, logout
Organizations	10	Multi-tenant workspaces, members, roles
Templates	7	Token template CRUD, variations
Objects	8	Tokenized asset instances, search, hierarchy
Actions (Event Bus)	7	Execute actions, batch operations, action types
Faces	6	Visual representations (image, 3D, web)
Storage	4	File upload, asset management
Webhooks	6	Real-time event subscriptions
Notifications	5	Message sending, templates
Sequencer	4	Batch and ZK-rollup checkpoint queries
API Keys	3	Programmatic access management
Payments	2	Payment config, deposit history
Support	3	Feature access requests, support messages
Public API	5	Read-only public endpoints (no auth)

AI Services (34 tools)

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

Module	Tools	Description
Intelligence	12	Autonomous agents, lifecycle predictions, trending, anomalies, knowledge graph
Governance	14	Compliance rules & evaluation, audit log, policy parsing, provenance verification
Creative	8	Token design generation, face templates, SVG rendering

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

Variable	Description	Required
DUAL_API_KEY	API key for DUAL platform authentication	One of these
DUAL_ACCESS_TOKEN	JWT access token	One of these
DUAL_REFRESH_TOKEN	JWT refresh token	No
DUAL_API_URL	API base URL (default: https://api.blockv-labs.io/v3)	No
TRANSPORT	stdio (default) or http	No
PORT	HTTP port (default: 3100)	No
HOST	HTTP bind address (default: 127.0.0.1)	No
MCP_SERVER_API_KEY	Shared secret for HTTP endpoint auth	Yes (HTTP mode)
CORS_ORIGIN	Comma-separated allowed origins (e.g. https://app.example.com)	No
RATE_LIMIT_MAX	Max requests per minute per IP (default: 100)	No

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.

Variable	Default	Service
INTELLIGENCE_URL	http://localhost:3201	Intelligence (agents, predictions, graph)
GOVERNANCE_URL	http://localhost:3202	Governance (compliance, provenance, policies)
CREATIVE_URL	http://localhost:3203	Creative (token design, face rendering)

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