MCP Server Setup Guide

A step-by-step guide to installing, configuring, and using the DUAL MCP Server with your AI assistant. By the end of this guide, you'll have an AI agent that can mint tokens, manage templates, execute actions, and interact with the full DUAL platform through natural language.

Prerequisites

Node.js 18+— Required runtime

npm or yarn— Package manager

DUAL account— For API access

MCP client— Claude Desktop, Cursor, or any MCP-compatible tool

Installation

Clone the Repository

git clone https://github.com/ro-ro-b/dual-mcp-server.git
cd dual-mcp-server

Install Dependencies

npm install

This installs the MCP SDK, Zod for input validation, Axios for HTTP requests, and TypeScript tooling.

Build the Server

npm run build

Compiles TypeScript to JavaScript in the dist/ directory. The entry point is dist/index.js.

Authentication

The MCP server needs credentials to interact with the DUAL API. You have three options — choose the one that fits your workflow.

Option A: API Key (Recommended)

Best for server-to-server integrations. Create an API key in the DUAL dashboard, then set the environment variable:

ENVIRONMENT VARIABLE

export DUAL_API_KEY=your-api-key-here

API keys persist across sessions and don't expire like JWT tokens. This is the recommended approach for production use.

Option B: JWT Access Token

If you already have a JWT token from a login flow:

ENVIRONMENT VARIABLE

export DUAL_ACCESS_TOKEN=your-jwt-token
export DUAL_REFRESH_TOKEN=your-refresh-token  # optional

JWT tokens expire, so you may need to use dual_refresh_token periodically.

Option C: Interactive Login

No pre-configured credentials? The AI agent can log in interactively using the dual_login tool. Just tell the agent “log in to DUAL” and provide your email and password when prompted.

Interactive login sets the auth token for the current session only. It won't persist after the server restarts.

Client Configuration

Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

claude_desktop_config.json

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

Restart Claude Desktop after saving. You should see DUAL tools available in the tool picker.

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json in your project or global config):

.cursor/mcp.json

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

Claude Code (CLI)

Add via the Claude Code CLI:

claude mcp add dual node /path/to/dual-mcp-server/dist/index.js

Then set the API key in your shell environment before running Claude Code.

HTTP Transport (Remote)

For remote deployment or multi-client scenarios, run the server in HTTP mode:

TRANSPORT=http PORT=3100 DUAL_API_KEY=your-key node dist/index.js

The MCP endpoint is available at http://localhost:3100/mcp and a health check at /health.

Usage Examples

Once configured, you can interact with the DUAL platform through natural language. Here are real-world examples of what your AI agent can do.

Create a Reward Token

“Create a redeemable reward token called BrandPoints with a 1 million supply. Add an expiry property that defaults to 12 months from mint date.”

dual_create_template — Creates the BrandPoints template with points, expiry_date, and redeemable properties

dual_create_action_type — Registers 'Redeem' and 'Expire' actions with payload schemas

dual_create_face — Attaches a visual representation to the template

dual_execute_action — Mints the initial supply of 1M tokens

Monitor Platform Activity

“How many objects are on the platform? Show me the latest sequencer batch and any recent checkpoints.”

dual_public_get_stats — Fetches total objects, templates, and wallets

dual_list_batches — Gets the latest sequencer batch with transactions

dual_list_checkpoints — Shows recent ZK-rollup checkpoints with state roots

Set Up Webhooks for Real-Time Events

“Set up a webhook to notify my server whenever a token is transferred. Send test payloads to make sure it works.”

dual_create_webhook — Registers an HTTPS endpoint for transfer events

dual_test_webhook — Sends a test payload to verify the endpoint responds

dual_list_webhooks — Confirms the webhook is active and correctly scoped

Manage Organizations and Members

“Create an organization called Acme Corp, set up an admin role and a viewer role, then add my team member.”

dual_create_organization — Creates the Acme Corp workspace

dual_create_org_role — Creates 'Admin' role with full permissions

dual_create_org_role — Creates 'Viewer' role with read-only permissions

dual_add_org_member — Adds the team member with the appropriate role

Batch Operations (Atomic)

“Transfer 100 tokens to three different wallets and update the status to distributed — all in one atomic batch.”

dual_batch_actions — Executes all 4 actions atomically — 3 transfers + 1 status update. If any fails, all roll back.

Environment Variables Reference

Variable	Description	Required
`DUAL_API_KEY`	API key for 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

Troubleshooting

"Error: Authentication required"

No credentials configured. Set DUAL_API_KEY or DUAL_ACCESS_TOKEN environment variable, or use the dual_login tool to authenticate interactively.

"Error: Cannot reach DUAL API"

Check your network connection and verify DUAL_API_URL is correct. The default URL is https://api.blockv-labs.io/v3.

Tools not showing in Claude Desktop

Make sure the path in claude_desktop_config.json is absolute (not relative). Restart Claude Desktop after editing the config.

"Error: Rate limit exceeded"

You're making too many requests. Wait a moment and try again. For high-volume operations, use dual_batch_actions to group multiple actions.

JWT token expired

Use dual_refresh_token with your refresh token, or set up an API key which doesn't expire.

Next Steps

MCP Server ReferenceFull tool list and API module reference

TypeScript SDKUse the SDK directly for custom integrations

API ReferenceOpenAPI 3.1 spec with 70 paths

Learn DUALAI-generated learning resources via Google NotebookLM