@fuul/mcp-server

Fuul Model Context Protocol server for managing affiliate programs, analytics, incentives, and payouts through MCP-compatible clients (Claude Code, Cursor, Claude Desktop).

Table of Contents

• Quick Start

• Installation Methods

  • Claude Code Plugin (Recommended)

  • Cursor IDE

  • npx (Any MCP Client)

  • Local Development (Clone)

• Authentication

• Configuration

• MCP Tool Reference

• Troubleshooting

• Repository Layout

• Scripts Reference

• Documentation

• CI and Releases

• License

Quick Start

# 1. Install (choose one method below)
# 2. Authenticate once:
npx -y --package=@fuul/mcp-server@latest fuul-mcp login

# 3. Verify:
npx -y --package=@fuul/mcp-server@latest fuul-mcp whoami

Installation Methods

1. Claude Code Plugin (Recommended)

The easiest way to use Fuul MCP with Claude Code. Adds the MCP server plus a skill that documents how to use Fuul tools.

Step 1: Install the plugin

/plugin marketplace add kuyen-labs/mcp_server
/plugin install fuul-mcp@fuul-mcp

Step 2: Verify the .mcp.json format

Check the plugin's .mcp.json at:

~/.claude/plugins/cache/fuul-mcp/fuul-mcp/<version>/.mcp.json

It must use the --package= format in args:

{
  "mcpServers": {
    "fuul": {
      "command": "npx",
      "args": ["-y", "--package=@fuul/mcp-server@latest", "fuul-mcp-server"],
      "env": {
        "FUUL_API_BASE_URL": "${user_config.FUUL_API_BASE_URL}"
      }
    }
  }
}

If args shows ["-y", "@fuul/mcp-server@latest", "fuul-mcp-server"] (without --package=), update it to match the format above.

Step 3: Reload the plugin

/reload-plugins

Step 4: Authenticate (one-time)

Open a terminal and run:

npx -y --package=@fuul/mcp-server@latest fuul-mcp login

This opens your browser for OAuth. Tokens are saved to ~/.fuul/tokens.json.

Step 5: Verify

npx -y --package=@fuul/mcp-server@latest fuul-mcp whoami

Optional: Use staging environment

Set FUUL_API_BASE_URL in the plugin's user settings:

2. Cursor IDE

Option A: Using npx (no clone required)

1. Authenticate first:

   npx -y --package=@fuul/mcp-server@latest fuul-mcp login
   npx -y --package=@fuul/mcp-server@latest fuul-mcp whoami

2. Configure MCP in Cursor:

   Go to Settings → MCP or edit your mcp.json:

   {
     "mcpServers": {
       "fuul": {
         "command": "npx",
         "args": ["-y", "--package=@fuul/mcp-server@latest", "fuul-mcp-server"],
         "env": {
           "FUUL_API_BASE_URL": "https://api.fuul.xyz"
         }
       }
     }
   }

Option B: Using local clone

1. Clone and build:

   git clone https://github.com/kuyen-labs/mcp_server.git
   cd mcp_server
   npm ci
   npm run build

2. Authenticate:

   npm run cli -- login
   npm run cli -- whoami

3. Configure MCP in Cursor:

   {
     "mcpServers": {
       "fuul": {
         "command": "node",
         "args": ["C:\\path\\to\\mcp_server\\dist\\index.js"],
         "cwd": "C:\\path\\to\\mcp_server"
       }
     }
   }

   On macOS/Linux:

   {
     "mcpServers": {
       "fuul": {
         "command": "node",
         "args": ["/path/to/mcp_server/dist/index.js"],
         "cwd": "/path/to/mcp_server"
       }
     }
   }

3. npx (Any MCP Client)

Use the published npm package without cloning:

For MCP client configs (JSON), use the --package= format:

{
  "command": "npx",
  "args": ["-y", "--package=@fuul/mcp-server@latest", "fuul-mcp-server"]
}

4. Local Development (Clone)

git clone https://github.com/kuyen-labs/mcp_server.git
cd mcp_server
npm ci
cp .env.example .env   # Optional: edit for staging/custom settings
npm run build

Run CLI commands:

npm run cli -- login
npm run cli -- whoami
npm run cli -- logout

Run MCP server:

npm start              # Production (uses dist/)
npm run dev            # Development (uses tsx, watches src/)

Debug with MCP Inspector:

npm run build
npx @modelcontextprotocol/inspector node dist/index.js

Authentication

Authentication uses OAuth with the Fuul dashboard. Tokens are stored locally and shared by the CLI and MCP server.

Token location

Login flow

npx -y --package=@fuul/mcp-server@latest fuul-mcp login

This opens your default browser to the Fuul OAuth page. After authorizing, tokens are saved automatically.

Verify session

npx -y --package=@fuul/mcp-server@latest fuul-mcp whoami

Clear tokens

npx -y --package=@fuul/mcp-server@latest fuul-mcp logout

Configuration

Environment variables are read from process.env and, when present, a .env file in the current working directory.

Example .env file

FUUL_API_BASE_URL=https://api.stg.fuul.xyz
FUUL_MCP_DEBUG=1

Note: The .env file is for local development only and is not included in the npm package. Tokens are stored in ~/.fuul/tokens.json, not in .env.

MCP Tool Reference

Tool Categories

Tool Examples

All tools receive JSON arguments. Use real UUIDs from your tenant.

Health checks

// ping (no auth required)
{}

// whoami (requires login)
{}

Metadata queries

// list_chains, list_trigger_types, list_payout_schemas
{}

Project operations

// list_projects
{ "page": 1, "query": "acme" }

// get_project
{ "project_id": "550e8400-e29b-41d4-a716-446655440000" }

Incentives

// list_incentives
{ "project_id": "<uuid>" }

// get_incentive
{ "project_id": "<uuid>", "conversion_id": "<uuid>" }

// get_trigger
{ "project_id": "<uuid>", "trigger_id": "<uuid>" }

Agents (Claude Code): draft vs published trigger IDs — see plugin skill plugins/fuul-mcp/skills/fuul/SKILL.md § Draft vs published.

Affiliate analytics

// get_affiliate_portal_stats (single affiliate)
{
  "project_id": "<uuid>",
  "user_identifier": "evm:0x1234..."
}

// get_project_affiliate_total_stats (project totals)
{
  "project_id": "<uuid>",
  "dateRange": "30d"
}

// get_project_affiliates_breakdown (grouped breakdown)
{
  "project_id": "<uuid>",
  "groupBy": "region",
  "dateRange": "30d"
}

groupBy options: audience, tier, region, status

dateRange options: 7d, 30d, 90d, MTD, QTD, custom, all

Events (project API key)

Requires FUUL_MCP_PROJECT_API_KEY or project_api_key on each call. Writes use dry_run then confirmed.

// check_event_status (ingestion only)
{
  "user_identifier": "0x80Fe27F878d2d42BD8b387F3cA4b96CBDEc05326",
  "user_identifier_type": "evm_address",
  "event_name": "trade"
}

// check_event_status (full pipeline after send_event)
{
  "verbose": true,
  "dedup_id": "4bdabf2c-271a-4d66-afd0-a9f24119810a",
  "event_name": "trade"
}

// send_event (dry_run preview)
{
  "name": "trade",
  "user_identifier": "0x80Fe27F878d2d42BD8b387F3cA4b96CBDEc05326",
  "user_identifier_type": "evm_address",
  "dedup_id": "4bdabf2c-271a-4d66-afd0-a9f24119810a",
  "args": { "volume": 1000 },
  "dry_run": true
}

// send_batch_events (confirmed)
{
  "events": [
    {
      "name": "trade",
      "user_identifier": "0x80Fe27F878d2d42BD8b387F3cA4b96CBDEc05326",
      "user_identifier_type": "evm_address",
      "dedup_id": "batch-id-1"
    }
  ],
  "confirmed": true
}

Payout operations

// list_payouts_pending_approval
{ "project_id": "<uuid>", "page": 1, "page_size": 50 }

// list_rewards_payouts
{ "project_id": "<uuid>", "page": 1 }

Write Operations (Two-Step Flow)

All mutation tools require a two-step process:

1. Preview: Call with dry_run: true — validates and returns a preview without making changes

2. Confirm: Call with confirmed: true — executes the mutation

Example: Approve payouts

// Step 1: Preview
{
  "project_id": "<uuid>",
  "payout_ids": ["<uuid1>", "<uuid2>"],
  "dry_run": true
}

// Step 2: Confirm (after user approval)
{
  "project_id": "<uuid>",
  "payout_ids": ["<uuid1>", "<uuid2>"],
  "confirmed": true
}

Write tools: approve_payouts, reject_payouts, update_project_tier, update_audience, update_trigger, update_payout_term

Troubleshooting

MCP server fails to start

Symptom: Error like Cannot find package '@fuul/mcp-server' or binary not found.

Solution: Ensure you use the --package= format in args:

{
  "args": ["-y", "--package=@fuul/mcp-server@latest", "fuul-mcp-server"]
}

Wrong:

{
  "args": ["-y", "@fuul/mcp-server@latest", "fuul-mcp-server"]
}

401 Unauthorized errors

Symptom: API tools return 401 or whoami fails.

Solution:

1. Run login again:

   npx -y --package=@fuul/mcp-server@latest fuul-mcp login

2. Verify tokens exist:

   • macOS/Linux: ~/.fuul/tokens.json

   • Windows: %USERPROFILE%\.fuul\tokens.json

3. Verify session:

   npx -y --package=@fuul/mcp-server@latest fuul-mcp whoami

Rate limiting (HTTP 429)

Symptom: Tools return 429 errors.

Solution: Wait for the Retry-After header duration, then retry. The MCP server handles this automatically in most cases.

Environment not loading

Symptom: Staging URL not being used despite .env file.

Solution:

1. Ensure cwd in your MCP config points to the directory containing .env

2. Or pass environment directly in the config:

   {
     "env": {
       "FUUL_API_BASE_URL": "https://api.stg.fuul.xyz"
     }
   }

Windows path issues

Symptom: Paths not resolving correctly on Windows.

Solution: Use double backslashes or forward slashes:

{
  "args": ["C:\\Users\\me\\mcp_server\\dist\\index.js"]
}

Or:

{
  "args": ["C:/Users/me/mcp_server/dist/index.js"]
}

Repository Layout

mcp_server/
├── .claude-plugin/           # Claude Code marketplace manifest
│   └── marketplace.json
├── .github/
│   ├── workflows/            # CI and release workflows
│   │   ├── ci.yml
│   │   └── release.yml
│   └── pull_request_template.md
├── docs/                     # Documentation
│   ├── README.md             # Docs index
│   ├── AGENTS.md             # Tool ↔ HTTP mapping
│   └── mcp-phase2/
│       ├── CONSUMER.md       # API expectations
│       └── tool-prompts.md   # Sample prompts for evals
├── plugins/
│   └── fuul-mcp/             # Claude Code plugin
│       ├── .claude-plugin/
│       │   └── plugin.json
│       ├── .mcp.json         # MCP server config
│       └── skills/
│           └── fuul/
│               └── SKILL.md  # Tool usage instructions
├── src/                      # TypeScript source
│   ├── affiliate-portal/     # Affiliate analytics
│   ├── agent/                # Write confirmation logic
│   ├── auth/                 # OAuth and tokens
│   ├── config/               # Environment config
│   ├── http/                 # HTTP client
│   ├── metadata/             # Chains, triggers, schemas
│   ├── payouts/              # Payout operations
│   ├── tools/                # MCP tool definitions
│   ├── triggers/             # Trigger operations
│   ├── util/                 # Utilities
│   ├── cli.ts                # CLI entry point
│   └── index.ts              # MCP server entry point
├── dist/                     # Compiled output (gitignored)
├── .env.example              # Environment template
├── CHANGELOG.md              # Release notes
├── package.json
├── release.config.cjs        # semantic-release config
├── tsconfig.json
└── vitest.config.ts

Scripts Reference

Documentation

CI and Releases

Continuous Integration

On each push/PR to main, master, beta, or alpha, GitHub Actions runs:

• lint — ESLint checks

• test — Vitest test suite

• build — TypeScript compilation

Publishing

Releases are automated via semantic-release and npm Trusted Publishing (OIDC):

1. Use Conventional Commits: feat:, fix:, BREAKING CHANGE:

2. Merge to main (or beta/alpha for pre-releases)

3. GitHub Actions runs semantic-release, which:

   • Determines the next version from commits

   • Updates package.json and CHANGELOG.md

   • Publishes to npm

   • Creates a GitHub release

No manual npm publish or GitHub Release creation needed.

Requirements

• Node.js 18 or higher

• A running fuul-server (staging or production) with Agent OAuth configured

License

MIT — see package.json