MCP Server

The KeeperHub MCP server exposes tools over the Model Context Protocol, enabling AI agents to create, execute, and monitor blockchain automation workflows.

Connect to KeeperHub MCP

Remote (recommended)

Connect directly to KeeperHub’s hosted MCP server. No local process or CLI installation needed.

claude mcp add --transport http keeperhub https://app.keeperhub.com/mcp

Then run /mcp inside Claude Code to complete the OAuth authorization via browser. KeeperHub will ask you to approve access, and the token is stored automatically.

For headless or CI environments where browser auth is not available, pass an API key:

claude mcp add --transport http keeperhub https://app.keeperhub.com/mcp \
  --header "Authorization: Bearer kh_your_key_here"

Via Claude Code Plugin

Install the Claude Code Plugin for additional skills and slash commands on top of the MCP tools. The plugin connects to the same remote endpoint.

Local via kh CLI (deprecated)

The kh CLI can run a local MCP server over stdio via kh serve --mcp. This is deprecated in favor of the remote endpoint above and will be removed in a future release.

Per-Workflow MCP Servers

In addition to the aggregate server at /mcp, every listed marketplace workflow is also reachable as its own narrow MCP server at /mcp/w/<slug>. The aggregate server exposes the generic call_workflow(slug, inputs) dispatcher; the per-workflow form registers a single tool named after the workflow’s listed slug, with the workflow’s actual input schema and description.

This matters because LLMs select tools from tools/list in a single decision step. A typed, named tool with a real input schema is picked in one turn. A generic dispatcher requires a multi-turn discover-then-call dance, costs more tokens, and has lower selection accuracy.

Install

claude mcp add --transport http my-workflow https://app.keeperhub.com/mcp/w/<slug> \
  --header "Authorization: Bearer kh_your_key_here"

Replace <slug> with the workflow’s listed slug (visible on its marketplace page) and my-workflow with whatever name you want the server to appear under. The same Bearer-token rules apply — any valid kh_ API key or OAuth token works.

What the agent sees

After install, the AI’s tool inventory gains exactly one tool: the workflow itself, with its real name as title, the workflow’s description, and the listed input schema. There is no search_workflows step and no call_workflow indirection. The LLM picks the tool by name and shape.

Cross-organization calls

Any valid bearer can call any listed workflow regardless of which organization owns the workflow. Listed workflows are open to all callers by design. Unlisted slugs return 404.

Paid workflows

Paid listings return an HTTP 402 with an x402 challenge. The MCP transport surfaces this as a tool error with the full challenge body in the response text. To autopay, install the agentic wallet — its PreToolUse safety hook intercepts the 402, evaluates the price against your safety thresholds, signs the payment, and retries.

Compared to the aggregate server

Removing

claude mcp remove my-workflow

Authentication

The MCP endpoint supports two authentication methods:

OAuth 2.1 (browser-based): When you add the remote MCP server, Claude Code discovers the OAuth metadata at /.well-known/oauth-authorization-server and opens a browser for authorization. Tokens are managed automatically (1-hour access tokens, 30-day refresh tokens).

API keys (headless): Pass an organization API key (kh_ prefix) as a Bearer token. Create one at app.keeperhub.com  under Settings > API Keys > Organisation tab.

Organization Scoping

Each MCP connection is scoped to a single organization. The org is determined by your authentication method:

• OAuth: The org active in your browser session when you approve the authorization request.
• API key: The org the key was created in (visible on the API Keys page).

All tools operate within this org — listing workflows, creating workflows, executing, and viewing integrations. There is no way to access another org’s resources from the same connection.

Switching Organizations

To work with a different org, re-authenticate:

OAuth (Claude Code): Switch your active org at app.keeperhub.com  using the org switcher, then reconnect the MCP server. In Claude Code, remove and re-add the server:

claude mcp remove keeperhub
claude mcp add --transport http keeperhub https://app.keeperhub.com/mcp

Complete the OAuth flow again — the new active org will be captured.

API key: Create a separate API key in the target org and update the MCP server configuration with the new key.

Working with Multiple Organizations

If you regularly work across multiple orgs, add a separate MCP server entry for each:

{
  "mcpServers": {
    "keeperhub-acme": {
      "type": "http",
      "url": "https://app.keeperhub.com/mcp",
      "headers": { "Authorization": "Bearer kh_acme_key" }
    },
    "keeperhub-personal": {
      "type": "http",
      "url": "https://app.keeperhub.com/mcp",
      "headers": { "Authorization": "Bearer kh_personal_key" }
    }
  }
}

Each server entry has its own tool namespace, so the AI agent can distinguish which org to target based on the server name.

Tools Reference

Workflow Management

Execution

AI Generation

Action Schemas

Plugins

Templates

Integrations

Documentation

Resources

The server exposes two MCP resources:

Creating a Workflow

A typical workflow creation flow:

1. Discover actions — call list_action_schemas with a category to see available action types and their required fields
2. Build nodes — construct trigger and action nodes with the correct actionType values
3. Connect nodes — define edges from trigger to actions in execution order
4. Create — call create_workflow with nodes and edges (auto-layouts positions)
5. Test — call execute_workflow and poll get_execution_status

Node Structure

{
  "id": "check-balance",
  "type": "action",
  "data": {
    "label": "Check Balance",
    "description": "Check wallet ETH balance",
    "type": "action",
    "config": {
      "actionType": "web3/check-balance",
      "network": "11155111",
      "address": "0x..."
    },
    "status": "idle"
  }
}

Trigger nodes use type: "trigger" with a triggerType in the config (Manual, Schedule, Webhook, Event).

Edge Structure

Edges connect nodes and define execution flow:

{
  "id": "edge-1",
  "source": "trigger-1",
  "target": "check-balance"
}

For Condition nodes and For Each nodes, edges require a sourceHandle field:

{
  "id": "edge-2",
  "source": "condition-1",
  "target": "send-alert",
  "sourceHandle": "true"
}

Condition Nodes

Condition nodes have dual output paths with true and false source handles. Connect downstream nodes to the appropriate handle to create if/else logic in a single Condition node.

Conditions support these operators: == (soft equals), === (equals), != (soft not equals), !== (not equals), >, >=, <, <=, contains, startsWith, endsWith, matchesRegex, isEmpty, isNotEmpty, exists, doesNotExist, isNull, isNotNull, isUndefined, isNotUndefined.

Conditions reference previous node outputs using template syntax: {{@nodeId:Label.field}}.

Web3 Action Reference

Read Actions (no wallet required)

Write Actions (require wallet integration)

Get the walletId by calling get_wallet_integration.

The network field accepts chain IDs as strings: "1" (Ethereum mainnet), "11155111" (Sepolia), "8453" (Base), "42161" (Arbitrum), "137" (Polygon).

abiFunction field

For web3/read-contract and web3/write-contract, the abiFunction field is the function as it appears in the contract’s ABI. Pass the plain name for unique functions ("balanceOf") or the full signature for overloaded ones ("transfer(address,uint256)").

Error Handling

All tools return errors in this format:

{
  "content": [{ "type": "text", "text": "Error: <message>" }],
  "isError": true
}