Skip to main content
Glama
Sign In
deenesjakoruzh
@runehand/mcp-server

@runehand/mcp-server

by echelonlabs-sf
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

@runehand/mcp-server

MCP server that wraps the Runehand public API v1 as tools, so an MCP client (Claude Desktop, Claude Code, etc.) can operate Runehand bots directly: list bots and flows, read and reply to conversations, manage leads, and check analytics.

Setup

  1. Generate an API key at https://app.runehand.co/settings/api-keys (requires a Pro or Enterprise plan, and the owner or admin role in the workspace). The plaintext key is shown once — copy it.

  2. Add this to your MCP client's config (example: Claude Desktop's claude_desktop_config.json):

{
  "mcpServers": {
    "runehand": {
      "command": "npx",
      "args": ["-y", "@runehand/mcp-server"],
      "env": { "RUNEHAND_API_KEY": "rh_live_..." }
    }
  }
}

  1. Restart your MCP client. It should now list 9 Runehand tools.

Related MCP server: eduframe-mcp

Configuration

Env var

Required

Default

Purpose

RUNEHAND_API_KEY

Yes

—

Bearer token from /settings/api-keys.

RUNEHAND_API_BASE_URL

No

https://app.runehand.co/api/v1

Override for local/staging testing only.

Tools

Tool

Description

list_bots

List the bots that belong to the workspace that owns the API key.

list_flows

List the flows that belong to a bot, given the bot's UUID.

get_flow

Get a single flow, including its nodes in executable format.

list_conversations

List conversations, optionally filtered by bot_id and/or status.

get_conversation

Get a single conversation, including its messages.

send_message

Send a message as the agent in an existing conversation.

list_leads

List leads, optionally filtered by bot_id and/or status.

create_lead

Create a lead directly, without an associated conversation.

get_analytics

Get workspace KPIs and quick stats for a date range.

Errors from the Runehand API surface as tool errors in the form "{code}: {message}" (e.g. not_found: Not found.) — see the error codes table below.

Errors

All error responses from /api/v1/* use the same shape:

{
  "error": {
    "code": "plan_upgrade_required",
    "message": "Your current plan does not include API access.",
    "details": {
      "required_tiers": ["pro", "enterprise"]
    }
  }
}

details is null when not applicable.

Code

HTTP

When

unauthenticated

401

Missing header, invalid/revoked/expired token

workspace_inactive

403

Workspace is frozen or subscription lapsed

plan_upgrade_required

403

Workspace's plan doesn't include API access

validation_failed

422

Request data failed validation

not_found

404

Resource doesn't exist or doesn't belong to the key's workspace

rate_limited

429

Plan's requests-per-minute limit exceeded

server_error

500

Unhandled internal error

Development

npm install
npm run dev      # run directly with tsx, no build step
npm test         # vitest, mocks all HTTP via msw
npm run lint
npm run typecheck
npm run build     # compiles to dist/

License

MIT

Available Tools

9 tools
create_leadCreate leadB

Create a lead directly, without an associated conversation. Does not trigger the LeadCaptured event.

Inputs: bot_id (required), name, tags, email, +4 more.

get_analyticsGet analytics dashboardA

Get workspace KPIs and quick stats for a date range, same data as the in-app dashboard.

Inputs: to, from.

get_conversationGet conversation detailA

Get a single conversation, including its messages in chronological order.

Inputs: conversation_id (required).

get_flowGet flow detailB

Get a single flow, including its nodes in executable format.

Inputs: flow_id (required).

list_botsList botsB

List the bots that belong to the workspace that owns the API key.

Inputs: page, per_page.

list_conversationsList conversationsA

List conversations for the workspace, optionally filtered by bot_id and/or status.

Inputs: page, bot_id, status, per_page.

list_flowsList flowsC

List the flows that belong to a bot, given the bot's UUID.

Inputs: bot_id (required), page, per_page.

list_leadsList leadsB

List leads for the workspace, optionally filtered by bot_id and/or status.

Inputs: page, bot_id, status, per_page.

send_messageSend messageA

Send a message as the agent in an existing conversation. Delivers to the external channel (WhatsApp, Telegram, etc.) when the conversation is not on the web channel.

Inputs: content (required), conversation_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.6/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool targets a distinct resource or action: bots, flows, conversations, analytics, messaging, and leads. The list/get pairs follow a clear resource-detail distinction, so an agent can reliably select the intended tool.

    Naming Consistency5/5

    All tools use lowercase snake_case verb_noun naming: list_*, get_*, send_message, create_lead. The pattern is consistent and predictable across the entire surface.

    Tool Count5/5

    Nine tools is well-scoped for a workspace/bot/conversation/lead management server. Each tool corresponds to a meaningful operation, and there is no redundant bloat.

    Completeness4/5

    Read/query coverage is strong across bots, flows, conversations, leads, and analytics, with messaging and lead creation included. Minor gaps exist—no lead status update, conversation creation/closure, or flow editing—but these are likely handled outside this server's read-and-engage scope.

    Resources

    Related MCP Connectors

    Related MCP Servers