MCP Server

The packages/mcp-server package (@runeya/packages-mcp-server) exposes Runeya tools to AI clients via the Model Context Protocol (MCP). It allows an external AI agent (e.g. Claude Desktop) to control Runeya — list services, start, stop, and retrieve their logs.

Role in the Architecture

AI Client (e.g. Claude Desktop)
        │ MCP (stdio)
┌───────▼──────────────────────┐
│      MCP Server (stdio)      │
│  packages/mcp-server         │
└───────┬──────────────────────┘
        │ HTTP tRPC
┌───────▼──────────────────────┐
│   Local Server (port 9545)   │
│   apps/server                │
└──────────────────────────────┘

The MCP Server is an independent Node.js process that communicates with its AI client via stdio (standard MCP transport) and forwards commands to the Runeya local server via HTTP.

Environment Variables

Variable	Default	Description
RUNEYA_BASE_URL	http://localhost:4000	URL of the Runeya local server
RUNEYA_CONVERSATION_ID	(empty)	Conversation ID — activates the ask_user tool in scenario mode
RUNEYA_INTERNAL_TOKEN	(empty)	Internal token — required alongside RUNEYA_CONVERSATION_ID

Server port

By default, the Runeya server listens on port 9545. Set RUNEYA_BASE_URL=http://localhost:9545 if your server is running on that port.

Exposed MCP Tools

Tools are defined in packages/shared via RUNEYA_TOOL_DEFINITIONS and registered dynamically.

MCP Tool	tRPC Route	Description
list_services	service.list	List all Runeya services
get_service_status	process.status	Get the status of a service
start_service	process.start	Start a service
stop_service	process.stop	Stop a service
restart_service	process.restart	Restart a service
get_logs	process.logs	Retrieve logs of a service
ask_user (scenario)	scenario.requestInput	Ask the user a question and wait for their reply

Common Parameters

All tools that operate on a service accept:

Parameter	Type	Description
serviceId	string	UUID of the service
agentId	string	UUID of the Runeya agent running the service
authToken	string (optional)	JWT Bearer token for authentication

ask_user Tool (scenario mode only)

The ask_user tool is only available when both RUNEYA_CONVERSATION_ID and RUNEYA_INTERNAL_TOKEN are set. It is used within Runeya scenarios for ask_user nodes, allowing the AI to request clarification from the user and wait for a response (timeout: 5 minutes).

Authentication

Each tRPC call can include an authToken (Bearer JWT). In standard mode, the MCP Server forwards this token from the tool input to the Authorization header of the HTTP request.

In scenario mode, RUNEYA_INTERNAL_TOKEN is used directly for calls to scenario.requestInput.

Transport

The MCP Server exclusively uses the stdio transport — it reads MCP requests from stdin and writes responses to stdout. It does not open any network port.

Integration with Claude Desktop

Example configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "runeya": {
      "command": "node",
      "args": ["/path/to/runeya/packages/mcp-server/dist/index.js"],
      "env": {
        "RUNEYA_BASE_URL": "http://localhost:9545"
      }
    }
  }
}

Once configured, Claude Desktop can use Runeya tools directly in its conversations to control your development environment services.

Dependencies

Package	Role
@modelcontextprotocol/sdk	Official MCP SDK (server + stdio transport)
@runeya/packages-shared	Tool definitions (RUNEYA_TOOL_DEFINITIONS)
zod	Input schema validation for tools