@cypherindustries/factory-mcp-server

MCP (Model Context Protocol) server for the Cypher Factory bonding curve launchpad. Use with Claude Code, Cursor, Windsurf, Cline, or any MCP-compatible client.

This server uses the McpServer class with per-tool registerTool() registration, Zod input schemas, and behavioral annotations on all 57 tools. It is a thin adapter over @cypherindustries/factory-sdk -- the SDK owns all tool definitions and execution logic.

Requirements

• Node.js >= 24

Installation

npm install -g @cypherindustries/factory-mcp-server
# or run directly
npx @cypherindustries/factory-mcp-server

Setup

Claude Code

Add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "cypher-factory": {
      "command": "npx",
      "args": ["@cypherindustries/factory-mcp-server"],
      "env": {
        "CYPHER_KEYSTORE_PASSWORD": "your-strong-password",
        "CYPHER_RPC_URL": "wss://ethereum-rpc.publicnode.com",
        "CYPHER_EXPLORER_URL": "https://etherscan.io",
        "CYPHER_API_BASE_URL": "https://api.factory.cyphereth.com"
      }
    }
  }
}

Cursor

Add to Cursor Settings > MCP Servers:

{
  "cypher-factory": {
    "command": "npx",
    "args": ["@cypherindustries/factory-mcp-server"],
    "env": {
      "CYPHER_KEYSTORE_PASSWORD": "your-strong-password",
      "CYPHER_RPC_URL": "wss://..."
    }
  }
}

Windsurf / Cline

Follow the same pattern -- add an MCP server entry with the command npx @cypherindustries/factory-mcp-server and the required environment variables.

Environment Variables

Wallet (at least one for write operations)

| Variable | Description | |----------|-------------| | CYPHER_KEYSTORE_PASSWORD | Password for encrypted keystore at ~/.cypher-factory/ (recommended) | | CYPHER_PRIVATE_KEY | Agent wallet private key (hex) |

Optional (defaults to Ethereum Mainnet)

| Variable | Description | Default | |----------|-------------|---------| | CYPHER_RPC_URL | RPC endpoint | wss://ethereum-rpc.publicnode.com | | CYPHER_FACTORY_ADDRESS | BCTokenFactory contract | Ethereum Mainnet default | | CYPHER_BONDING_CURVE_ADDRESS | BondingCurve contract | Ethereum Mainnet default | | CYPHER_HIGHLIGHTS_ADDRESS | HighlightsManager contract | Ethereum Mainnet default | | CYPHER_REFERRAL_ADDRESS | ReferralManager contract | Ethereum Mainnet default | | CYPHER_VESTING_ADDRESS | TokenVesting contract | Ethereum Mainnet default | | CYPHER_PLUGIN_FACTORY_ADDRESS | AlgebraFeePluginFactory | Ethereum Mainnet default | | CYPHER_CURVE_MATH_ADDRESS | CurveMath contract | Ethereum Mainnet default | | CYPHER_EXPLORER_URL | Block explorer base URL for transaction links | -- | | CYPHER_API_BASE_URL | REST API base URL for token queries and image upload | -- | | CYPHER_REFERRAL_BASE_URL | Referral link base URL | -- | | CYPHER_REFERRER_ADDRESS | Default referrer address for affiliate tracking | -- |

Unprefixed variants (FACTORY_ADDRESS, RPC_URL, etc.) are also accepted as fallbacks.

Transaction Gate

| Variable | Description | Default | |----------|-------------|---------| | MAX_PER_TX_ETH | Max ETH per transaction | 1 | | DAILY_BUDGET_ETH | Rolling 24h ETH budget | 5 | | COOLDOWN_SECONDS | Min seconds between writes | 2 |

Tool Annotations

All 57 tools are registered with MCP behavioral annotations that help clients understand tool behavior:

| Annotation | Description | |------------|-------------| | readOnlyHint | true if the tool does not modify on-chain or local state | | destructiveHint | true if the tool spends ETH or modifies state irreversibly | | idempotentHint | true if repeated calls with the same params produce the same result | | openWorldHint | true if the tool interacts with external systems (blockchain RPC, REST API) |

MCP clients can use these annotations to filter, sort, or auto-approve tool calls. For example, a client may auto-approve all readOnlyHint: true tools while requiring confirmation for destructiveHint: true tools.

Annotation Categories

| Category | readOnly | destructive | idempotent | openWorld | Example Tools | |----------|----------|-------------|------------|-----------|---------------| | Read (on-chain) | true | false | true | true | get_token_state, quote_buy, get_balance | | Read (API) | true | false | true | true | get_token_list, get_user_holdings | | Read (local) | true | false | true | false | get_config, spending_stats | | Read (strategy) | true | false | true | false | get_strategy_status, list_available_strategies | | Read (generate) | true | false | true | false | generate_referral_link, describe_protocol | | Write (ETH) | false | true | false | true | buy_token, sell_token, deploy_token | | Write (upload) | false | false | true | true | upload_image | | Config | false | false | true | false | update_config, update_tx_gate | | Config (strategy) | false | false | false | false | start_strategy, stop_strategy |

MCP Registry

The server includes a server.json file following the MCP Registry schema:

• Namespace: io.github.cypherindustries/factory-launchpad (reverse-DNS format)
• Package: @cypherindustries/factory-mcp-server on npm
• Environment variables: Documented in the registry metadata for automated setup

MCP Registry-compatible clients can discover and configure this server automatically using the server.json metadata.

Available Tools

The server exposes 57 tools. All tool names use snake_case (no prefix). For the complete reference with parameters and return types, see API-REFERENCE.md.

Read (no gas) -- 38 tools

• get_token_state -- full token info: price, supply, TVL, graduation status, fee decomposition
• quote_buy / quote_sell -- price quotes (CurveMath exact calculations)
• get_balance -- check ETH, WETH, or token balance
• check_graduation -- graduation cost estimate + caller fee (auto-graduation detection)
• check_otc_transfer -- pre-flight check for direct transfers
• get_highlight_status / get_highlight_config -- promotion cost and settings
• get_referral_reward / get_referral_fees -- referral earnings and fee structure
• get_cooldown_status -- staking vault cooldown
• get_staking_vault_address / get_staking_position -- staking vault lookup and position
• get_vesting_info / get_all_vesting_schedules -- vesting schedule details
• get_config -- current agent config + spending stats
• is_protocol_paused / get_creation_fee -- protocol status
• calculate_cost / preview_stake / preview_unstake -- read-only previews
• spending_stats / get_wallet_info / get_wallet_balances -- wallet and budget info
• get_failed_txs -- dead letter queue
• get_tx_history -- rolling confirmed transaction history (filter by type)
• get_portfolio_summary -- aggregated portfolio (ETH, tokens, staking, vesting, referrals)
• resolve_token / get_recent_deployments -- token registry
• get_token_list / get_token_distribution / get_user_holdings / get_user_creations / get_current_highlight -- API queries
• get_strategy_status / list_available_strategies -- strategy status
• generate_referral_link / describe_protocol -- generation tools

Write (costs gas, gated by TxGate) -- 15 tools

• buy_token / sell_token -- trade on bonding curve (with explorer links on tx receipt)
• deploy_token -- create a new token (with social links and staking vault default-on)
• trigger_graduation -- push token past MAX_SUPPLY
• upload_image -- upload image via REST API
• stake_tokens / request_unstake / request_unstake_by_shares / complete_unstake -- staking
• highlight_token / claim_referral_reward / otc_transfer -- highlights, referrals, transfers
• release_vested_tokens / create_vesting_schedule -- vesting management
• send_eth -- native ETH transfer with TxGate budget tracking

Config -- 4 tools

• update_config -- change slippage, risk limits, gas settings
• update_tx_gate -- change spending limits, blacklist
• start_strategy / stop_strategy -- manage automated trading strategies (requires wss:// RPC)

Architecture

MCP Client (Claude Code / Cursor / etc.)
  |
  | stdio (JSON-RPC)
  |
  v
McpServer (this package)
  |
  +-- WalletManager (from SDK)
  +-- LaunchpadAgent (from SDK)
  +-- ToolExecutor (from SDK, with TxGate)
  |     +-- TOOL_DEFINITIONS (57 tools)
  |     +-- TxGate (spending limits)
  |
  +-- registerTool() per tool:
  |     +-- title (human-readable)
  |     +-- description
  |     +-- inputSchema (Zod via zod-compat)
  |     +-- annotations (behavioral hints)
  |
  +-- 15 resources (11 static + 4 template-based)
  +-- 11 prompts (workflow guides)
  +-- Resource subscriptions (change notifications)
  |
  +-- makeToolCallback(toolName, executor) -> MCP response

The server uses McpServer (from @modelcontextprotocol/sdk) with individual registerTool() calls for each tool, enabling per-tool metadata (title, annotations, Zod schemas).

MCP Resources (15 total)

Static resources (11): cypher://protocol, cypher://wallet, cypher://config, cypher://positions, cypher://strategies, cypher://failed-transactions, cypher://staking, cypher://vesting, cypher://referrals, cypher://tx-history, cypher://portfolio

Template-based resources (4): cypher://positions/{token_address}, cypher://strategies/{strategy_name}, cypher://staking/{token_address}, cypher://vesting/{token_address}

MCP Prompts (11 total)

evaluate-trade, deploy-token, monitor-positions, manage-strategies, check-graduation, staking-workflow, referral-setup, vesting-management, otc-transfer, highlight-promotion, error-recovery

Resource Subscriptions

The server supports MCP resource subscriptions for change notifications. Subscribed URIs receive debounced (500ms) notifications on relevant events:

• cypher://wallet, cypher://positions, cypher://tx-history, cypher://portfolio -- on tx_confirmed events
• cypher://strategies -- on strategy start/stop events
• cypher://config -- polled every 15 seconds for changes

Security

• The MCP server creates a TxGate with configurable spending limits from environment variables.
• Interactive confirmation is disabled (confirmAboveETH: 0) since MCP does not support interactive prompts.
• Wallet source is logged to stderr on startup (keystore, env/config, or read-only mode).
• If no private key or keystore is configured, the server starts in read-only mode (write tools will error).
• Graceful shutdown with AbortController cancels in-flight operations and rolls back pending TxGate reservations.
• Chain-ID verification — on the first write operation the agent calls provider.getNetwork() and refuses to submit the transaction unless the provider's chain ID matches ConnectionConfig.expectedChainId (default: Ethereum Mainnet — 1). Prevents an accidentally-swapped CYPHER_RPC_URL from executing trades against whatever contracts happen to live at the hardcoded Ethereum Mainnet addresses on another chain.
• Bigint-safe resource serialization — every cypher://... resource handler uses the SDK's safeJsonStringify helper, so resources whose payload contains wei amounts (e.g. cypher://wallet with a live TxGate.getStats()) are round-trippable instead of crashing with a Do not know how to serialize a BigInt TypeError.

Changes

See CHANGELOG.md for the full v1.2.0 release notes.

Development

# From monorepo root
git clone https://github.com/CypherIndustries/factory-agent-sdk
cd factory-agent-sdk
pnpm install
pnpm build:mcp

# Test locally
CYPHER_KEYSTORE_PASSWORD=... node packages/mcp-server/dist/index.js

License

MIT