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

DUAL account— For API access

DUAL API key— From the DUAL Console

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

Internet connection— Hosted server — no local install needed

The DUAL MCP server is fully hosted at https://mcp.blockv.io/mcp — no Node.js, cloning, or building required. Just configure your MCP client to connect.

Authentication

The hosted MCP server authenticates requests using your API key sent via the X-API-Key header. You have two options.

Option A: API Key (Recommended)

Create an API key in the DUAL Console, then pass it to your MCP client via the headers configuration. No environment variables or local server setup required.

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

Option B: 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 OTP code when prompted.

Interactive login sets the auth token for the current session only.

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": {
      "url": "https://mcp.blockv.io/mcp",
      "headers": {
        "X-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": {
      "url": "https://mcp.blockv.io/mcp",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

Claude Code (CLI)

Add via the Claude Code CLI:

claude mcp add dual --transport sse https://mcp.blockv.io/mcp

Set the API key header in your MCP client configuration or shell environment.

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.

Configuration Reference

Setting	Description	Required
`url`	MCP endpoint: https://mcp.blockv.io/mcp	Yes
`X-API-Key header`	Your DUAL API key for authentication	Yes

Troubleshooting

"Error: Authentication required"

No API key configured. Ensure the X-API-Key header is set in your MCP client config, or use the dual_login tool to authenticate interactively.

"Error: Cannot reach DUAL MCP"

Check your internet connection. The hosted endpoint is https://mcp.blockv.io/mcp — verify it is reachable from your network.

Tools not showing in Claude Desktop

Verify the url field in claude_desktop_config.json is correct and headers include your API key. 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.

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