Skip to main content
Glama

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

Related MCP server: Bink MCP Server

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

Available Tools

80 tools
dual_add_org_memberAdd Organization MemberB
Idempotent

Add a wallet as a member to an organization with a specific role.

Inputs: organization_id (required), wallet_id (required), role_id (required).

dual_batch_actionsExecute Batch ActionsA

Execute multiple actions atomically in a single batch. All actions succeed or all fail. Useful for complex operations like: mint + transfer + configure in one transaction.

Inputs: actions (required).

dual_count_objectsCount ObjectsA
Read-onlyIdempotent

Count objects matching filter criteria without returning the full objects.

Inputs: filter (required).

dual_create_action_typeCreate Action TypeA

Register a new action type with an optional JSON schema for payload validation.

Inputs: name (required), description, schema.

dual_create_api_keyCreate API KeyA

Create a new API key for server-to-server integration. The key value is only shown once — save it immediately.

Inputs: name (required), permissions.

dual_create_faceCreate FaceB

Create a visual face for a template. Types: image, image_progress, image_policy, image_layered, 3d, web.

Inputs: template_id (required), display_url (required), type (required), platform.

dual_create_message_templateCreate Message TemplateB

Create a notification template with subject, body (with placeholders), and delivery channels.

Inputs: name (required), subject (required), body (required), channels (required).

dual_create_organizationCreate OrganizationA

Create a new organization (multi-tenant workspace). Returns the org with its ID and FQDN.

Inputs: name (required), fqdn, description, image.

dual_create_org_roleCreate Organization RoleB

Create a new role with specific permissions for an organization.

Inputs: organization_id (required), name (required), permissions (required).

dual_create_templateCreate TemplateA

Create a new token template that defines the structure of tokenized objects. Specify the property schema, allowed actions, and access rules. Example: Create a "Reward Token" template with properties like points, expiry_date, and redeemable status.

Inputs: name (required), object (required), fqdn, actions, +1 more.

dual_create_template_variationCreate Template VariationB

Create a variation of an existing template with overridden properties.

Inputs: template_id (required), name (required), object (required).

dual_create_webhookCreate WebhookA

Register a webhook to receive real-time notifications when events occur on the platform.

Inputs: url (required), type (required), template_id, action, +1 more.

dual_delete_api_keyDelete API KeyA
DestructiveIdempotent

Permanently revoke and delete an API key.

Inputs: api_key_id (required).

dual_delete_faceDelete FaceA
DestructiveIdempotent

Delete a face definition.

Inputs: face_id (required).

dual_delete_fileDelete FileB
DestructiveIdempotent

Delete a file from DUAL storage.

Inputs: file_id (required).

dual_delete_message_templateDelete Message TemplateB
DestructiveIdempotent

Delete a message template.

Inputs: template_id (required).

dual_delete_templateDelete TemplateA
DestructiveIdempotent

Permanently delete a template. This cannot be undone.

Inputs: template_id (required).

dual_delete_webhookDelete WebhookA
DestructiveIdempotent

Delete a webhook subscription.

Inputs: webhook_id (required).

dual_execute_actionExecute ActionA

Execute an action on a tokenized object via the Event Bus. Actions are the primary way to change object state. Examples: mint tokens, transfer ownership, redeem rewards, update status. The action_type must match a registered action type, and the object must belong to a template that allows it.

Inputs: action_type (required), object_id (required), payload.

dual_get_actionGet Action DetailsB
Read-onlyIdempotent

Get full details of a specific executed action.

Inputs: action_id (required).

dual_get_batchGet Batch DetailsB
Read-onlyIdempotent

Get details of a sequencer batch including all contained transactions.

Inputs: batch_id (required).

dual_get_checkpointGet ZK CheckpointA
Read-onlyIdempotent

Get a specific ZK-rollup checkpoint with its proof data and state roots.

Inputs: checkpoint_id (required).

dual_get_faceGet FaceB
Read-onlyIdempotent

Get details of a specific face.

Inputs: face_id (required).

dual_get_fileGet FileB
Read-onlyIdempotent

Get a file's URL or content by its storage ID.

Inputs: file_id (required), no_redirect.

dual_get_meGet Current WalletA
Read-onlyIdempotent

Get the authenticated wallet's profile — ID, nickname, email, avatar, language, activation status.

Inputs: no named parameters.

dual_get_objectGet ObjectB
Read-onlyIdempotent

Get full details of a tokenized object — its properties, ownership, faces, actions, and metadata.

Inputs: object_id (required).

dual_get_object_activityGet Object ActivityA
Read-onlyIdempotent

Get the full activity/audit log for an object — all state changes, transfers, and action executions.

Inputs: object_id (required), limit.

dual_get_object_childrenGet Object ChildrenB
Read-onlyIdempotent

Get child objects in a hierarchical object tree.

Inputs: object_id (required).

dual_get_object_parentsGet Object ParentsB
Read-onlyIdempotent

Get parent objects in a hierarchical object tree.

Inputs: object_id (required).

dual_get_organizationGet OrganizationB
Read-onlyIdempotent

Get organization details including members, roles, and account info.

Inputs: organization_id (required).

dual_get_org_balanceGet Organization BalanceB
Read-onlyIdempotent

Get the current balance and currency for an organization.

Inputs: organization_id (required).

dual_get_payment_configGet Payment ConfigurationA
Read-onlyIdempotent

Get the platform's payment configuration — deposit addresses, supported tokens, and fee structure.

Inputs: no named parameters.

dual_get_templateGet TemplateB
Read-onlyIdempotent

Get full details of a template including its property schema, actions, and factory config.

Inputs: template_id (required).

dual_get_template_assetsGet Template AssetsB
Read-onlyIdempotent

List all storage assets associated with a template.

Inputs: template_id (required).

dual_get_template_facesGet Template FacesA
Read-onlyIdempotent

Get all faces associated with a specific template.

Inputs: template_id (required).

dual_get_walletGet Wallet by IDB
Read-onlyIdempotent

Retrieve a wallet's public profile by its ID.

Inputs: wallet_id (required).

dual_get_webhookGet WebhookB
Read-onlyIdempotent

Get details of a specific webhook.

Inputs: webhook_id (required).

dual_list_actionsList ActionsB
Read-onlyIdempotent

List executed actions. Filter by action ID or template.

Inputs: action_id, template_id, limit, next.

dual_list_action_typesList Action TypesA
Read-onlyIdempotent

List all registered action types. Action types define what operations can be performed on objects.

Inputs: name, limit.

dual_list_api_keysList API KeysB
Read-onlyIdempotent

List all API keys for the authenticated wallet.

Inputs: no named parameters.

dual_list_batchesList Sequencer BatchesB
Read-onlyIdempotent

List sequencer batches. Batches group multiple transactions for efficient on-chain anchoring via ZK-rollup.

Inputs: limit, next.

dual_list_checkpointsList ZK CheckpointsA
Read-onlyIdempotent

List ZK-rollup checkpoints. Each checkpoint contains a state root and proof that anchors batches to L1.

Inputs: prev_state_root, next_state_root, limit, next.

dual_list_depositsList DepositsB
Read-onlyIdempotent

List deposit transactions. Filter by transaction hash, token, or token address.

Inputs: tx_hash, token, token_address, limit, +1 more.

dual_list_facesList FacesA
Read-onlyIdempotent

List face definitions. Faces are visual representations (images, 3D models, web views) attached to templates.

Inputs: limit, next.

dual_list_messagesList MessagesA
Read-onlyIdempotent

List notification messages sent through the platform.

Inputs: limit, next.

dual_list_message_templatesList Message TemplatesB
Read-onlyIdempotent

List all notification message templates.

Inputs: no named parameters.

dual_list_objectsList ObjectsA
Read-onlyIdempotent

List tokenized objects (asset instances). Objects are created from templates and owned by wallets. Filter by template, owner, FQDN, or geographic hash. Supports pagination.

Inputs: template_id, owner, fqdn, dropped, +3 more.

dual_list_organizationsList OrganizationsA
Read-onlyIdempotent

List all organizations the authenticated wallet belongs to. Supports pagination and role filtering.

Inputs: role_name, limit, next.

dual_list_org_membersList Organization MembersB
Read-onlyIdempotent

List all members of an organization with their roles.

Inputs: organization_id (required).

dual_list_org_rolesList Organization RolesB
Read-onlyIdempotent

List all roles defined for an organization.

Inputs: organization_id (required).

dual_list_support_messagesList Support MessagesC
Read-onlyIdempotent

List support messages.

Inputs: wallet_id, prefix, limit, next.

dual_list_templatesList TemplatesA
Read-onlyIdempotent

List token templates. Templates define the structure, properties, and actions of tokenized objects. Filter by prefix or FQDN.

Inputs: prefix, fqdn, limit, next.

dual_list_template_variationsList Template VariationsB
Read-onlyIdempotent

List all variations of a template. Variations are alternative configurations of the same template.

Inputs: template_id (required).

dual_list_webhooksList WebhooksA
Read-onlyIdempotent

List all registered webhooks. Filter by type, template, action, or active status.

Inputs: type, template_id, action, is_active.

dual_loginLogin to DUALA
Idempotent

Authenticate with email/phone and password. Returns JWT tokens for subsequent API calls. Sets auth automatically for this session.

Inputs: password (required), email, phone_number, otp.

dual_login_guestGuest LoginA

Create a guest session with limited permissions. No credentials required.

Inputs: nickname.

dual_public_get_objectGet Public ObjectA
Read-onlyIdempotent

Get a public object's details. No authentication required.

Inputs: object_id (required).

dual_public_get_statsGet Platform StatisticsA
Read-onlyIdempotent

Get public platform statistics — total objects, templates, and wallets. No authentication required.

Inputs: no named parameters.

dual_public_get_templateGet Public TemplateA
Read-onlyIdempotent

Get a public template's details. No authentication required.

Inputs: template_id (required).

dual_public_list_templatesList Public TemplatesA
Read-onlyIdempotent

List publicly accessible templates. No authentication required.

Inputs: fqdn, limit, next.

dual_public_search_objectsSearch Public ObjectsA
Read-onlyIdempotent

Search publicly accessible objects. No authentication required.

Inputs: filter (required), limit.

dual_refresh_tokenRefresh Access TokenA
Idempotent

Exchange a refresh token for a new access token.

Inputs: refresh_token (required).

dual_registerRegister DUAL WalletA

Create a new wallet account. A verification code will be sent to the email/phone provided.

Inputs: password (required), email, phone_number, nickname.

dual_register_verifyVerify RegistrationB
Idempotent

Complete registration by submitting the verification code sent to your email/phone.

Inputs: code (required).

dual_remove_org_memberRemove Organization MemberA
DestructiveIdempotent

Remove a member from an organization.

Inputs: organization_id (required), member_id (required).

dual_request_accessRequest Feature AccessA
Idempotent

Request access to a gated platform feature.

Inputs: feature (required), reason.

dual_reset_passwordRequest Password ResetA
Idempotent

Send a password reset code to the wallet's email/phone.

Inputs: email, phone_number.

dual_reset_password_verifyVerify Password ResetB
Idempotent

Submit reset code and set a new password.

Inputs: code (required), new_password (required).

dual_search_objectsSearch ObjectsB
Read-onlyIdempotent

Search tokenized objects with filter criteria. Supports complex queries across all object properties. Example filters: { "template_id": "abc123", "properties.status": "active" }

Inputs: filter (required), sort, limit.

dual_send_notificationSend NotificationB

Send a notification message to one or more wallets using a message template.

Inputs: to (required), template_id (required), subject, body, +1 more.

dual_send_support_messageSend Support MessageB

Send a support message to the DUAL team.

Inputs: subject (required), body (required), public.

dual_test_webhookTest WebhookA
Idempotent

Send a test payload to a webhook endpoint to verify it's working.

Inputs: webhook_id (required), payload.

dual_update_action_typeUpdate Action TypeB
Idempotent

Update an action type's name, description, or payload schema.

Inputs: action_type_id (required), name, description, schema.

dual_update_faceUpdate FaceB
Idempotent

Update a face's display URL or type.

Inputs: face_id (required), display_url, type.

dual_update_meUpdate Current WalletA
Idempotent

Update the authenticated wallet's nickname, language, or avatar.

Inputs: nickname, language, avatar.

dual_update_objectUpdate Object PropertiesB
Idempotent

Update the properties of a tokenized object. Only mutable properties can be changed.

Inputs: object_id (required), properties (required).

dual_update_organizationUpdate OrganizationB
Idempotent

Update an organization's name, description, or image.

Inputs: organization_id (required), name, description, image.

dual_update_templateUpdate TemplateA
Idempotent

Update a template's name, property schema, or access rules.

Inputs: template_id (required), name, object, public_access.

dual_update_webhookUpdate WebhookB
Idempotent

Update a webhook's URL or active status.

Inputs: webhook_id (required), url, is_active.

dual_upload_fileUpload FileA

Upload a file to DUAL storage. Returns a public URL. Useful for template assets, face images, and attachments.

Inputs: file_url (required), folder.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 80 tools

    Disambiguation3/5

    Most tools have distinct purposes, but there is significant overlap in some areas, such as multiple 'list' tools for different resources (e.g., dual_list_objects, dual_search_objects, dual_public_search_objects) and similar 'get' operations across entities, which could cause confusion. Descriptions help clarify, but the sheer number of tools increases ambiguity risk.

    Naming Consistency4/5

    Tool names follow a consistent 'dual_verb_noun' pattern throughout, with clear action-object pairs (e.g., dual_create_template, dual_update_object). Minor deviations exist, like dual_get_me instead of dual_get_wallet_me, but overall naming is predictable and readable.

    Tool Count2/5

    With 80 tools, the count is excessive for a single server, making it overwhelming and likely to cause agent confusion. While the domain (a multi-feature platform) is broad, this many tools suggests poor scoping and could be split into multiple focused servers for better usability.

    Completeness5/5

    The tool set provides comprehensive coverage for the platform's domain, including CRUD operations for templates, objects, organizations, and webhooks, plus authentication, notifications, and public access. No obvious gaps are present; it supports full lifecycle management and complex workflows like batch actions and search.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Provides permissionless wallet infrastructure for AI agents to manage wallets, sign transactions, and handle tokens across Solana and all EVM-compatible chains. It includes 29 specialized tools for on-chain operations, featuring built-in security guards and automated x402 payment processing without KYC requirements.
      40
      399 npm
      3
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to perform blockchain operations like wallet management, token info, DeFi swaps, cross-chain bridging, and price checking across Ethereum, BNB Chain, and Solana.
      ISC
    • A
      license
      B
      quality
      D
      maintenance
      Provides AI agents with 40 tools for structured data storage, querying, web search, URL fetching, scheduled jobs, and execution through the Model Context Protocol.
      44
      49 npm
      MIT