Alpha-MCP

Alpha-MCP is a V2-only Polymarket MCP server for agents that need a small, predictable tool surface instead of hundreds of raw endpoints.

What ships now:

• 51 MCP tools total (discoverable via tools/list)
• one natural-language entry point: alpha_intent
• V2-only Polymarket trading and market data
• read-only X health and rate-status tools
• native support for both OpenClaw and Hermes over stdio

Polymarket V2 note:

• Alpha-MCP targets Polymarket CLOB V2 at https://clob.polymarket.com.
• Trading uses pUSD collateral. API-only wallets must wrap USDC.e -> pUSD via the Collateral Onramp before placing orders.

Install

Run the interactive setup:

npx @ghostnetwork/openclaw-alpha-mcp setup

Or target a specific harness explicitly:

npx @ghostnetwork/openclaw-alpha-mcp setup --host openclaw
npx @ghostnetwork/openclaw-alpha-mcp setup --host hermes

Run the MCP server over stdio:

npx @ghostnetwork/openclaw-alpha-mcp

Run the built-in install checker:

npx @ghostnetwork/openclaw-alpha-mcp doctor
npx @ghostnetwork/openclaw-alpha-mcp doctor --host openclaw
npx @ghostnetwork/openclaw-alpha-mcp doctor --host hermes --json

Check the currently published npm version:

npm view @ghostnetwork/openclaw-alpha-mcp version

Or from source:

npm install
npm run build
node dist/server/index.js --stdio

Manifests in-repo:

• mcp.json (MCP server manifest)
• plugin.json (plugin-style descriptor for host registries)
• smithery.yaml (Smithery integration manifest)

Native harness setup

Alpha-MCP supports both OpenClaw and Hermes natively. This repository is host-first for production reliability: OpenClaw and Hermes are the supported deployment targets.

OpenClaw

OpenClaw MCP has two modes:

• openclaw mcp serve = OpenClaw itself acts as an MCP server for OpenClaw conversations.
• openclaw mcp set/list/show/unset = OpenClaw stores outbound MCP server definitions under mcp.servers.

Alpha-MCP uses the second mode (outbound server definition via mcp.servers) and runs over stdio (command + args).

openclaw mcp set alpha-mcp '{"command":"npx","args":["-y","@ghostnetwork/openclaw-alpha-mcp@latest"],"env":{"ALPHA_MCP_HOST":"openclaw","PM_ADDRESS":"0x...","PM_API_KEY":"...","PM_SECRET":"...","PM_PASSPHRASE":"...","PM_TRADING_ENABLED":"true"}}'

If OpenClaw injects credential env vars from its managed environment, alpha-mcp will use those process env values directly. A physical ~/.openclaw/.env file is optional in that setup.

Hermes

Add this to ~/.hermes/config.yaml:

toolsets:
  - mcp

mcp_servers:
  alpha_mcp:
    command: "npx"
    args: ["-y", "@ghostnetwork/openclaw-alpha-mcp@latest"]
    env:
      ALPHA_MCP_HOST: "hermes"
      PM_ADDRESS: "0x..."
      PM_API_KEY: "..."
      PM_SECRET: "..."
      PM_PASSPHRASE: "..."
      PM_TRADING_ENABLED: "true"
    enabled: true
    tools:
      resources: false
      prompts: false

Hermes quickstart order is: hermes setup -> hermes model -> verify a normal chat first, then add MCP servers. Hermes stores secrets in ~/.hermes/.env and non-secret config in ~/.hermes/config.yaml.

Hermes treats MCP servers as instance-wide consumers and supports per-server tool filtering in config, including tools.include, tools.exclude, tools.resources: false, tools.prompts: false, and enabled: false.

Tool layout

• alpha_intent - natural-language router for agent messages
• alpha_read_* - markets, orderbook, positions, health, price history, resolution
• alpha_trade_* - place, cancel, cancel-all-for-market
• alpha_rewards_* - rewards readiness and reward reads
• alpha_data_* - fee parameters, token lookup, balances, server time
• alpha_x_* - X health and rate status only
• poly_health - compatibility alias for health probes

Natural-language routing

Agents can use Alpha-MCP with a single tool:

alpha_intent({ message: "show my open orders" })
alpha_intent({ message: "check health status" })
alpha_intent({ message: "buy $1 YES market order token_id 123456" })

The router parses the message, identifies the action, extracts trade fields when possible, and applies fixed risk caps before any trade dispatch.

Fixed risk policy

These limits are enforced and were not changed in this rewrite:

• bankroll cap: 5 USDC
• max order: 1 USDC
• max market exposure: 2 USDC
• daily loss limit: 1 USDC
• max open orders: 2

Environment

npx @ghostnetwork/openclaw-alpha-mcp setup can write a local harness env file and install the packaged Polymarket skill into that harness's skill directory. Managed harnesses may instead inject env vars directly into the MCP subprocess.

At runtime, Alpha-MCP supports both harnesses with this order:

• explicit MCP env values win
• injected process env values from the harness are used directly
• ALPHA_MCP_HOST=openclaw reads ~/.openclaw/.env
• ALPHA_MCP_HOST=hermes reads ~/.hermes/.env
• if only one harness env file exists, Alpha-MCP selects it automatically
• if both exist, set ALPHA_MCP_HOST explicitly so startup stays deterministic

Supported selector:

ALPHA_MCP_HOST=openclaw
ALPHA_MCP_HOST=hermes

Doctor

alpha-mcp doctor validates the local install before you open the agent:

• resolves the target harness
• checks the selected harness env file or injected process env
• checks whether the packaged skill is installed in the harness skill directory
• checks OpenClaw mcp.servers or Hermes mcp_servers for alpha-mcp
• verifies route count, health payload, intent routing, and risk blocking logic

Use --json for machine-readable output.

OpenClaw connection failures are often silent in chat. If tools do not appear, check the gateway log and run alpha-mcp doctor --host openclaw --json.

Common variables:

PM_ADDRESS=0x...
PM_API_KEY=...
PM_SECRET=...
PM_PASSPHRASE=...
PM_PRIVATE_KEY=0x...
PM_FUNDER_ADDRESS=0x...
PM_SIGNATURE_TYPE=2
PM_BUILDER_CODE=0x...
PM_CLOB_BASE=https://clob.polymarket.com
X_BEARER_TOKEN=...

Compatibility aliases accepted by alpha-mcp (maps to canonical PM_* keys):

CLOB_API_KEY=...
CLOB_SECRET=...
CLOB_PASSPHRASE=...
POLYMARKET_FUNDER=0x...

Validation targets for this rewrite

• dist/ builds cleanly
• compiled JavaScript passes node --check
• tool discovery reports 51 tools in the current catalog build
• poly_health returns status: ok
• alpha_intent routes read-only requests correctly
• alpha_intent blocks trades that breach the fixed risk caps
• npm audit --omit=dev --audit-level=moderate exits cleanly