AI Integration with Model Context Protocol (MCP)

The Resonance MCP Server enables AI assistants like Claude, ChatGPT, and Cursor to directly integrate, manage, and build complete Resonance loyalty programs—including gamification features like streaks, leaderboards, achievements, and perks—through natural conversation.

What is MCP?

Model Context Protocol (MCP) is an open standard that allows AI assistants to:

Invoke Tools: Execute actions (API calls, file operations)
Access Resources: Read structured data (configs, schemas)
Maintain Context: Understand domain-specific information

Why Use MCP for Resonance?

Instead of manually reading documentation and writing integration code, you can simply describe what you want:

Traditional Integration Flow:
Developer → Reads Docs → Writes Code → Tests → Debugs → Ships

AI-Native Integration Flow:
Developer → Describes Intent → AI Invokes MCP → Validates → Ships

Installation

Prerequisites

Node.js 18+ installed
Claude Desktop, Cursor, or another MCP-compatible AI assistant

Install the MCP Server

Option 1: Install from npm (Recommended)

npm install -g @resonance/mcp-server

Or install locally:

npm install @resonance/mcp-server

Option 2: Install from GitHub

git clone https://github.com/Alpha4-Labs/resonance-mcp.git
cd resonance-mcp
npm install
npm run build

Configuration

Claude Desktop

Add to your Claude Desktop MCP configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

If installed via npm:

{
  "mcpServers": {
    "resonance": {
      "command": "npx",
      "args": ["@resonance/mcp-server"],
      "env": {
        "RESONANCE_NETWORK": "mainnet",
        "RESONANCE_BRAND_ID": "0x47511fc1c6664c9598974cb112965f8b198e0c725e"
      }
    }
  }
}

If installed from GitHub:

{
  "mcpServers": {
    "resonance": {
      "command": "node",
      "args": ["/path/to/resonance-mcp/dist/index.js"],
      "env": {
        "RESONANCE_NETWORK": "mainnet",
        "RESONANCE_BRAND_ID": "0x47511fc1c6664c9598974cb112965f8b198e0c725e"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json:

If installed via npm:

{
  "servers": {
    "resonance": {
      "command": "npx",
      "args": ["@resonance/mcp-server"],
      "env": {
        "RESONANCE_NETWORK": "mainnet",
        "RESONANCE_BRAND_ID": "your-brand-id-here"
      }
    }
  }
}

If installed from GitHub:

{
  "servers": {
    "resonance": {
      "command": "node",
      "args": ["/path/to/resonance-mcp/dist/index.js"],
      "env": {
        "RESONANCE_NETWORK": "mainnet",
        "RESONANCE_BRAND_ID": "your-brand-id-here"
      }
    }
  }
}

Environment Variables

RESONANCE_NETWORK: Network to use - mainnet (default) or testnet
RESONANCE_BRAND_ID: Your brand wallet address (optional, can also be provided per-tool)

Quick Start Examples

Example 1: Design a Loyalty Program

Simply describe what you want:

User: "Design a loyalty program for my developer Discord with events for 
quality contributions, daily check-ins, and helpful answers"

AI: [Uses resonance_design_program tool]
    Returns: Complete program with:
    - Event structure
    - Reward amounts
    - Implementation code
    - Best practices

Example 2: Add Daily Check-ins

User: "Add daily check-ins with streak bonuses to my Telegram bot"

AI: [Uses resonance_streak_checkin tool]
    Generates code:
    - Bot command handler
    - Streak tracking logic
    - Multiplier calculations
    - Milestone notifications

Example 3: Create Custom Events

User: "Create 5 events for my Telegram trading community: daily check-in, 
helpful answer, trade signal, referral, and milestone celebration"

AI: [Uses resonance_create_events_batch tool]
    Returns:
    - All created events with IDs
    - Telegram bot implementation code
    - Event tracking examples

Available Tools

The MCP server provides 24+ tools organized into categories:

Program Design

resonance_design_program - AI-powered program generation

Event Management

resonance_create_event - Create single custom event
resonance_create_events_batch - Create multiple events
resonance_track_event - Fire events and reward users
resonance_get_event_config - Get all configured events
resonance_bulk_events - Batch event tracking
resonance_admin_reward - Manual admin rewards

User Management

resonance_resolve_user - Convert platform identity to wallet
resonance_get_user_balance - Get user balance and history
resonance_check_eligibility - Check reward eligibility
resonance_get_user_stats - Comprehensive user statistics

Engagement & Gamification

resonance_streak_checkin - Process streak check-in
resonance_get_streak_status - Get streak status
resonance_claim_streak_milestone - Claim milestone bonuses
resonance_log_activity - Track voice/message activity
resonance_calculate_reward - Calculate rewards with multipliers
resonance_get_leaderboard - Get ranked leaderboards
resonance_update_leaderboard_stats - Update user stats

resonance_create_drop - Create time-limited reward drops
resonance_claim_drop - Process drop claims
resonance_process_third_party_event - Integrate with Mee6, Arcane, etc.

Perks & Redemption

resonance_list_perks - Get available perks
resonance_check_perk_eligibility - Check perk eligibility
resonance_redeem_perk - Redeem a perk

Achievements

resonance_get_user_achievements - Get user achievements
resonance_update_achievement_progress - Update achievement progress

Transactions

resonance_relay_transaction - Execute gasless transactions

Webhooks

resonance_validate_webhook - Validate webhook signature
resonance_webhook_example - Generate webhook receiver code

Diagnostics

resonance_health_check - Check API health status

Available Resources

The MCP server provides access to:

Documentation Resources

All developer documentation is available as MCP resources:

resonance://docs/architecture
resonance://docs/api/rest-api
resonance://docs/integrations/discord
resonance://docs/guides/custom-events
... and 50+ more documentation pages

Static Resources

Contracts: resonance://contracts/rsnc-token, resonance://contracts/perk-nft, resonance://contracts/all
Network: resonance://network/config - Soneium network configuration
Event Types: resonance://events/standard - Standard event types reference (includes channel constraints and domain validation)
Shared Services: resonance://shared-services/endpoints - API endpoints reference
OAuth Providers: resonance://platforms/mappings - OAuth provider ID formats
Error Codes: resonance://errors/codes - Complete HTTP status codes and error response reference
Error Handling: resonance://errors/handling - Error handling patterns and best practices
Rate Limits: resonance://rate-limits/endpoints - Rate limits by endpoint with reset periods
Rate Limit Strategies: resonance://rate-limits/strategies - Code examples for handling rate limits
SDK Methods: resonance://sdk/methods - JavaScript SDK method reference with examples
SDK Examples: resonance://sdk/examples - SDK usage examples for React, Vue, Next.js

BrandId Configuration

The brandId parameter is required for most operations. You can provide it in two ways:

Environment Variable (Recommended): Set RESONANCE_BRAND_ID in your MCP configuration
Tool Parameter: Provide brandId as a parameter to each tool call

If neither is provided, tools will return a helpful error message explaining how to set it up.

Common Use Cases

Discord Bot Integration

User: "Add loyalty rewards to my Discord bot. Reward users for:
- Daily check-ins (50 RSNC)
- Helpful answers (100 RSNC)
- Voice chat participation (10 RSNC per 5 minutes)"

AI generates complete Discord.js bot code with:
- Command handlers
- Event tracking
- Reward distribution
- Error handling

Telegram Bot Integration

User: "Create a Telegram bot that tracks daily check-ins with streaks"

AI generates complete Telegraf bot code with:
- /checkin command
- Streak tracking
- Milestone notifications
- Leaderboard integration

Web Integration

User: "Add loyalty rewards to my Next.js app for newsletter signups and purchases"

AI generates:
- React components
- API route handlers
- Event tracking hooks
- Balance display components

Best Practices

Set BrandId in Environment: Use RESONANCE_BRAND_ID environment variable for convenience
Use Resources: AI can access documentation resources to understand best practices
Test on Testnet: Use RESONANCE_NETWORK=testnet for testing
Check Eligibility: Use resonance_check_eligibility before tracking events
Update Leaderboards: Call resonance_update_leaderboard_stats after rewards

Troubleshooting

BrandId Not Found

If you see "BrandId is required but not provided":

Set RESONANCE_BRAND_ID in your MCP configuration, or
Provide brandId as a parameter to tool calls

Tool Not Found

Ensure you've built the project:

cd resonance-mcp
npm run build

Resource Not Found

Resources are loaded at server startup. Ensure:

Documentation files exist in the expected location
Resource URIs match the expected format

Architecture

AI Assistant (Claude/ChatGPT/Cursor)
    ↓ MCP Protocol
Resonance MCP Server
    ↓ HTTP API
Resonance APIs
    - Event Handler (api.rsnc.network)
    - Shared Services (services.rsnc.network)
    - Pregeneration (register.rsnc.network)

Security

No API keys required - uses public brandId identifier
All inputs validated server-side
Rate limiting awareness (documented limits)
Support for testnet/mainnet separation
BrandId can be set via environment variable for convenience

Next Steps

Install and configure the MCP server
Try a simple prompt: "Design a loyalty program for my Discord server"
Review the generated code and customize as needed
Deploy and test your integration

Recent Updates

The MCP server includes support for the latest Resonance features:

Boost Events: Custom Discord server boost events (first_boost, tier_1_boost, tier_2_boost, tier_3_boost, boost_tier_upgrade)
Natural Participation: Automatic rewards for GM/GN check-ins, quality messages, popular messages, auto-welcome, voice activity
Role Bonuses: Role-based multipliers (1.0-5.0x) and flat bonuses (0-1000 RSNC) for Discord roles
Max Claims: Clarified event-level vs drop-level max claims (999999 or -1 for unlimited)

Package Information

npm Package: @resonance/mcp-server
GitHub Repository: Alpha4-Labs/resonance-mcp
Version: 1.0.0
License: MIT

For more examples and detailed documentation, see the MCP Server README.

What is MCP?​

Why Use MCP for Resonance?​

Installation​

Prerequisites​

Install the MCP Server​

Configuration​

Claude Desktop​

Cursor​

Environment Variables​

Quick Start Examples​

Example 1: Design a Loyalty Program​

Example 2: Add Daily Check-ins​

Example 3: Create Custom Events​

Available Tools​

Program Design​

Event Management​

User Management​

Engagement & Gamification​

Social Features​

Perks & Redemption​

Achievements​

Transactions​

Webhooks​

Diagnostics​

Available Resources​

Documentation Resources​

Static Resources​

BrandId Configuration​

Common Use Cases​

Discord Bot Integration​

Telegram Bot Integration​

Web Integration​

Best Practices​

Troubleshooting​

BrandId Not Found​

Tool Not Found​

Resource Not Found​

Architecture​

Security​

Related Documentation​

Next Steps​

Recent Updates​

Package Information​