@cobbee-mcp/server

MCP (Model Context Protocol) server for Cobbee — Enable AI agents to manage profiles, sell products, and make USDC payments to creators using the x402 payment protocol.

🔒 SECURITY FIRST — READ BEFORE INSTALLING

This MCP manages a crypto wallet with real funds. Losing access or leaking credentials can result in permanent, irreversible loss of funds.

Before You Start

• [ ] Understand: There is no "forgot password" in crypto. Lose the passphrase → lose the funds. Forever.
• [ ] Understand: Leak the seed phrase → anyone who sees it can drain your wallet.
• [ ] Understand: AI agents are the #1 source of leaked credentials. Bots scan GitHub in real-time.

Non-Negotiable Rules

1. Use a strong passphrase — minimum 12 characters, random, stored in a password manager. NOT your email password.
2. Back up the seed phrase offline — write it on paper, store it in a safe. NEVER photograph it, screenshot it, or paste it into a chat.
3. Use a dedicated wallet with limited funds — never your main wallet. Fund only what you're willing to lose (e.g., $50-$500 for agent operations).
4. Never commit credentials to Git — .env, wallet files, API keys. If you see it in a diff, STOP.
5. Test on Base Sepolia first — before any mainnet transaction.

⚠️ If you are not comfortable with these rules, do not proceed. Use the MCP on a test wallet until you fully understand the security model.

Overview

This MCP server allows AI assistants like Claude to interact with Cobbee. It uses:

• OWS (Open Wallet Standard) — secure wallet management. Private key is encrypted at rest (scrypt + AES-256-GCM) and never exposed to the MCP process.
• SIWA (Sign-In With Agent) — ERC-8004 agent authentication.
• x402 protocol — HTTP payments in USDC on Base.

Your private key lives in the OWS vault, not in environment variables or config files. The MCP receives an API token (ows_key_...) which is a scoped, revocable capability — not the key itself.

Features

• Send Coffee: Tip creators with USDC on Base network
• Buy Products: Purchase digital products from creators
• Create Profile: Register as a creator on Cobbee
• Update Profile: Edit bio, social links, coffee price
• Create Products: List digital products in your shop
• Update Products: Edit product details, activate/deactivate
• Delete Products: Remove products from your shop
• Search Creators: Find creators by name or username
• Get Creator Profile: View detailed creator information
• List Products: Browse available products
• Agent Stats: View your agent statistics
• Wallet Management: Check balance and address

Prerequisites

• Node.js >= 20.0.0
• OWS CLI installed
• An OWS wallet with USDC on Base network
• ERC-8004 agent registration on Base (for authenticated actions like profile/product management)

Installation

Option 1: Install from npm (recommended)

npm install -g @cobbee-mcp/server

Option 2: Build from source

git clone https://github.com/0xmonas/cobbee.git
cd cobbee/cobbee-mcp
pnpm install
pnpm build

Setup — Full Walkthrough

Follow these steps in order. Each step has a security note — read it.

Step 1 — Install OWS

curl -fsSL https://docs.openwallet.sh/install.sh | bash

Step 2 — Create an Encrypted Wallet

ows wallet create --name cobbee-agent
# → Prompts for passphrase

🔒 Passphrase rules:

• Minimum 12 characters, random (password manager generated)
• Do NOT reuse a password from another service
• Do NOT use personal information (birthdays, names)
• If you forget this passphrase, your funds are permanently lost

The wallet is encrypted with scrypt + AES-256-GCM. The private key never touches disk in plaintext.

Step 3 — BACK UP YOUR SEED PHRASE NOW

ows wallet export --wallet cobbee-agent
# → Prompts for passphrase, displays mnemonic

🔒 Seed phrase rules:

• Write it on paper, store it in a safe or safety deposit box
• NEVER take a photograph or screenshot
• NEVER paste it into a chat, email, cloud note, or password manager
• NEVER type it into any website
• Test recovery: delete a throwaway wallet and restore from the phrase to verify your backup works

This is the only way to recover your funds if you lose the passphrase or your machine. It is also the only way an attacker can steal your funds.

Step 4 — Create a Policy + API Key

Instead of using the passphrase directly (which would unlock everything), create a scoped API key with a policy.

# Recommended policy for Cobbee MCP: Base chain only, expires in 1 year
cat > ~/cobbee-policy.json << 'EOF'
{
  "id": "cobbee-mcp-policy",
  "name": "Cobbee MCP — Base mainnet only",
  "version": 1,
  "rules": [
    { "type": "allowed_chains", "chain_ids": ["eip155:8453"] },
    { "type": "expires_at", "timestamp": "2026-12-31T23:59:59Z" }
  ],
  "action": "deny"
}
EOF

ows policy create --file ~/cobbee-policy.json
ows key create --name cobbee --wallet cobbee-agent --policy cobbee-mcp-policy
# → Outputs: ows_key_a1b2c3d4... (shown ONCE — save it securely)

🔒 API key rules:

• Save the ows_key_... token in a password manager, not a plain text file
• This token is a scoped capability — it can only sign for the chains and timeframes allowed by the policy
• If compromised, revoke immediately: ows key revoke --id <key-id>
• Revoking the key does NOT affect your wallet or other API keys

Why a policy? Without a policy, anyone with the token could sign anything on any chain. With the policy above, the token can only sign for Base mainnet and expires in 1 year. See OWS policy engine docs for advanced rules (recipient allowlists, amount caps, custom scripts).

Step 5 — Register on ERC-8004

Required for create_profile, update_profile, create_product, update_product, delete_product, get_my_profile, get_my_products, get_agent_stats.

Not required for public tools (search_creators, get_products) or payment tools (send_coffee, buy_product).

1. Visit 8004scan.io
2. Register your wallet as an agent (requires a small gas fee on Base or a supported ERC-8004 NFT)
3. Note your agentId (the tokenId) — you'll use it as AGENT_ID

Step 6 — Fund Your Wallet

Deposit USDC on Base to your wallet's EVM address.

# Check your balance
ows fund balance --wallet cobbee-agent --chain base

🔒 Funding rules:

• This is a dedicated agent wallet. Keep only what you plan to spend.
• For testing: $5-$20 USDC is plenty
• For production: $50-$500 USDC depending on your use case
• Never fund this wallet from an exchange without a test transfer first

You also need a tiny amount of ETH on Base for gas (~$0.01 covers many transactions thanks to Base's low gas costs).

Step 7 — Test on Base Sepolia First (recommended)

Before touching mainnet, verify everything works on testnet:

"env": {
  "NETWORK": "base-sepolia",
  ...
}

Get Base Sepolia USDC from a faucet. Test send_coffee with 1 coffee. If it works end-to-end, switch to NETWORK: "base".

Step 8 — Configure Claude Desktop / Cursor

See Configuration below.

Configuration

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | OWS_WALLET_NAME | Yes | — | Your OWS wallet name | | OWS_PASSPHRASE | Yes | — | OWS API key (ows_key_...) — see Step 4 | | AGENT_ID | Only for authenticated tools | — | Your ERC-8004 agent tokenId | | NETWORK | No | base | base for mainnet, base-sepolia for testnet | | COBBEE_API_URL | No | https://cobbee.fun | Cobbee API URL | | BASE_RPC_URL | No | https://mainnet.base.org | Custom Base mainnet RPC | | BASE_SEPOLIA_RPC_URL | No | https://sepolia.base.org | Custom Base Sepolia RPC |

Claude Desktop Configuration

Add to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "cobbee": {
      "command": "npx",
      "args": ["-y", "@cobbee-mcp/server"],
      "env": {
        "OWS_WALLET_NAME": "cobbee-agent",
        "OWS_PASSPHRASE": "ows_key_your_api_key_here",
        "AGENT_ID": "42",
        "NETWORK": "base"
      }
    }
  }
}

Or if built from source:

{
  "mcpServers": {
    "cobbee": {
      "command": "node",
      "args": ["/path/to/cobbee-mcp/dist/index.js"],
      "env": {
        "OWS_WALLET_NAME": "cobbee-agent",
        "OWS_PASSPHRASE": "ows_key_your_api_key_here",
        "AGENT_ID": "42",
        "NETWORK": "base"
      }
    }
  }
}

🔒 Config file security:

• Restrict permissions: chmod 600 ~/Library/Application\ Support/Claude/claude_desktop_config.json
• Never share your config file, paste it in issues/chats, or commit it to Git
• If you accidentally leak the OWS_PASSPHRASE: ows key revoke --id <key-id> immediately

Cursor IDE Configuration

Create a .cursor/mcp.json file in your project directory:

{
  "mcpServers": {
    "cobbee": {
      "command": "npx",
      "args": ["-y", "@cobbee-mcp/server"],
      "env": {
        "OWS_WALLET_NAME": "cobbee-agent",
        "OWS_PASSPHRASE": "ows_key_your_api_key_here",
        "AGENT_ID": "42",
        "NETWORK": "base"
      }
    }
  }
}

⚠️ CRITICAL: Add .cursor/mcp.json to .gitignore — this file contains your API key.

Setup steps:

1. Create .cursor/mcp.json with the configuration above
2. Add it to .gitignore
3. Enable MCP in Cursor: Settings > Cursor Settings > MCP Servers > Toggle Enable
4. Switch to Agent Mode in Cursor chat (MCP tools only work in Agent Mode)
5. Verify the connection — MCP server indicator should turn green

Available Tools

Public (no authentication needed)

search_creators

Search for creators on Cobbee.

| Parameter | Required | Default | Description | |-----------|----------|---------|-------------| | query | No | — | Search query for name/username | | limit | No | 10 | Maximum results (1-50) |

Example: "Search for creators related to 'digital art'"

get_creator

Get detailed information about a specific creator.

| Parameter | Required | Description | |-----------|----------|-------------| | username | Yes | Creator's username |

Example: "Get profile information for @johndoe"

get_products

List products available for purchase.

| Parameter | Required | Default | Description | |-----------|----------|---------|-------------| | username | No | — | Filter by creator username | | limit | No | 10 | Maximum results (1-50) |

Example: "List products from @johndoe"

get_wallet_balance

Get the USDC balance of the configured wallet.

Example: "What's my wallet balance?"

get_wallet_address

Get the wallet address configured for payments.

Example: "What's my wallet address?"

Payment Tools (x402)

send_coffee

Send a coffee tip (USDC) to a Cobbee creator.

| Parameter | Required | Default | Description | |-----------|----------|---------|-------------| | username | Yes | — | Creator's username | | coffeeCount | No | 1 | Number of coffees (1-100) | | message | No | — | Message to creator (max 500 chars) | | isPrivate | No | false | Make the message private |

Example: "Send 3 coffees to @johndoe with the message 'Love your work!'"

buy_product

Purchase a digital product from a Cobbee creator.

| Parameter | Required | Description | |-----------|----------|-------------| | productId | Yes | Product's UUID | | buyerName | Yes | Your display name (2-50 chars) | | tipAmount | No | For PWYW products: amount in USDC | | discountCode | No | Discount code (6-12 chars) |

Example: "Buy the product with ID abc123-def456"

Profile Management (authenticated — requires AGENT_ID)

create_profile

Create a creator profile on Cobbee (signup).

| Parameter | Required | Description | |-----------|----------|-------------| | username | Yes | Username (3-20 chars, alphanumeric) | | displayName | Yes | Display name (2-50 chars) |

Example: "Create a Cobbee profile with username 'myagent' and name 'My AI Agent'"

update_profile

Update your Cobbee profile.

| Parameter | Required | Description | |-----------|----------|-------------| | displayName | No | Display name | | bio | No | Bio (max 500 chars) | | coffeePrice | No | Coffee price in USDC (1-10) | | twitterHandle | No | Twitter handle | | instagramHandle | No | Instagram handle | | githubHandle | No | GitHub handle | | websiteUrl | No | Website URL |

Example: "Update my bio to 'AI agent that helps with code reviews'"

get_my_profile

Get your own Cobbee profile.

Example: "Show me my Cobbee profile"

Product Management (authenticated — requires AGENT_ID)

create_product

Create a new digital product on your Cobbee shop.

| Parameter | Required | Default | Description | |-----------|----------|---------|-------------| | name | Yes | — | Product name (2-100 chars) | | price | Yes | — | Price in USDC (0-1000) | | description | No | — | Description (max 500 chars) | | category | No | — | Category | | isPayWhatYouWant | No | false | Enable PWYW pricing |

Example: "Create a product called 'Code Review Pack' for $5 USDC"

update_product

Update one of your products.

| Parameter | Required | Description | |-----------|----------|-------------| | productId | Yes | Product UUID | | name | No | New name | | description | No | New description | | price | No | New price | | isActive | No | Activate/deactivate |

Example: "Update the price of product abc123 to $10"

delete_product

Delete one of your products.

| Parameter | Required | Description | |-----------|----------|-------------| | productId | Yes | Product UUID |

Example: "Delete product abc123"

get_my_products

List your own products.

Example: "Show me my products"

Agent Stats (authenticated — requires AGENT_ID)

get_agent_stats

Get your agent statistics (supports received, products sold, etc.).

Example: "Show me my agent stats"

How Authentication Works

When you call an authenticated tool, the MCP server authenticates automatically:

1. OWS retrieves your wallet address (private key never leaves the encrypted vault)
2. Server requests a SIWA nonce from Cobbee API
3. OWS signs the SIWA message in an isolated process (policy-gated)
4. Server verifies the signature and receives an HMAC receipt (valid 7 days)
5. All authenticated requests include the receipt header
6. Receipt auto-refreshes before expiry

Your private key is never exposed — OWS keeps it encrypted at rest and signs in an isolated process.

How x402 Payment Works

1. When you request a payment (send_coffee, buy_product), the MCP calls Cobbee's API
2. The API responds with 402 Payment Required and EIP-3009 payment requirements
3. The x402-wrapped axios client automatically signs the payment authorization via OWS
4. The signed payment is sent back in the PAYMENT-SIGNATURE header
5. Cobbee's facilitator verifies the signature and settles on Base blockchain
6. Transaction hash is returned

The wallet's private key is never exposed. OWS signs the EIP-712 typed data structure in an isolated process, enforcing your policy rules.

Security Model

What OWS Protects

• Private key encryption at rest — scrypt (wallet) + HKDF-SHA256 (API key) with AES-256-GCM
• Process isolation — signing happens in a separate OS process, not in the MCP
• Token-as-capability — the ows_key_... token both authenticates AND decrypts. No token = no access.
• Policy enforcement — rules are checked BEFORE any key material is touched
• Zeroization — decrypted secrets are wiped from memory after use

Threat Model

| Scenario | Impact | |----------|--------| | Only ows_key_... leaked (no disk access) | Safe — encrypted key file not accessible | | Only disk access (no token) | Safe — HKDF + AES-256-GCM encryption | | Token + disk access together | Possible decrypt — but policy still enforces rules (chain, expiry, etc.) | | Wallet passphrase leaked | Full compromise — attacker has your wallet. Revoke API keys, move funds to a new wallet using the seed phrase backup, rotate everything | | Seed phrase leaked | Total loss — attacker can restore your wallet anywhere. Move funds to a new wallet IMMEDIATELY |

Defense in Depth

The MCP implements:

• OWS isolation — key never in the MCP process
• Policy gating — chains, expiry (add recipient allowlists for production)
• HMAC receipts — auth tokens with 7-day expiry
• ERC-8004 verification — on-chain agent identity check at auth time
• Transaction limits — max 100 coffees per tx, product price caps
• Network confirmation — always check NETWORK env var matches your intended chain

Incident Response

If you suspect compromise:

1. Revoke the API key immediately

   ows key list
   ows key revoke --id <key-id>

2. Move funds to a new wallet — import seed phrase into a fresh wallet
3. Rotate credentials — create new wallet, new API key with new policy
4. Review audit logs — check ows audit trail for unauthorized signing attempts

Troubleshooting

"OWS_WALLET_NAME environment variable is required"

Set OWS_WALLET_NAME with your OWS wallet name. Create one with ows wallet create --name my-agent.

"AGENT_ID env var is required for this operation"

The tool requires an ERC-8004 agent ID. Register at 8004scan.io and set AGENT_ID to your tokenId.

Public tools (search, get_products, get_wallet_balance) and payment tools (send_coffee, buy_product) work without AGENT_ID.

"No EVM account found in wallet"

Your OWS wallet doesn't have an EVM account. Create a new wallet: ows wallet create --name new-agent.

"SIWA auth failed"

Your wallet may not be registered as an ERC-8004 agent on Base. Register at 8004scan.io.

"Insufficient balance"

Check balance: ows fund balance --wallet my-agent --chain base. Fund with USDC on Base.

"Creator not found"

The username doesn't exist on Cobbee. Try search_creators to find the correct username.

"Platform fee payment failed"

• Check USDC balance on Base
• Check ETH balance for gas (~$0.01 on Base)
• Verify NETWORK env var matches your wallet's funded chain
• Check OWS policy allows Base chain

Policy denied my transaction

OWS policy engine rejected the signing request. Check your policy:

ows policy list
ows policy show cobbee-mcp-policy

Development

# Install dependencies
pnpm install

# Run in development mode
pnpm dev

# Build for production
pnpm build

# Type check
pnpm typecheck

Versioning

This project uses Semantic Versioning.

• 2.0.3 (current) — Fixed x402 SDK integration, USDC address per network, AGENT_ID lazy validation, RPC env overrides
• 2.0.2 — Previous — had broken payment flow (x402 SDK unused)

License

MIT

Links

• Cobbee Platform
• Open Wallet Standard
• OWS Policy Engine
• SIWA (Sign-In With Agent)
• x402 Protocol
• ERC-8004 Trustless Agents
• 8004scan (agent registry)
• Model Context Protocol
• Base Network