mcp_server

An MCP (Model Context Protocol) server that exposes Underleaf edge-infrastructure capabilities as tools for AI coding assistants (Claude Desktop, VS Code Copilot Chat, Cursor, etc.).

The binary runs over stdio — the IDE spawns it on demand per session and communicates via JSON-RPC on stdin/stdout. All server-side logging goes to stderr, which most IDE integrations capture separately.

Tools

Group	Count	Target	Description
cluster_*	12	Agent localhost:2240	Raft cluster ops, KV store
mmesh_*	4	Agent localhost:2240	Mycelium Mesh event stream
provider_* / capability_*	5	Agent localhost:2240	Capability providers
servers_*	8	Control plane	Edge server management
expose_*	4	Control plane	Hyphae mTLS exposures
jobs_*	2	Control plane	Command execution jobs
templates_*	10	Control plane	Command templates + cron
deploy_*	5	Deployment engine localhost:8080	UMC lifecycle management

Total: 50 tools.

Configuration

Tools that call the remote control plane read ~/.underleaf/config.yaml:

api:
  base_url: https://api.underleaf.io   # Control-plane base URL
auth:
  token: <your-token>                   # Bearer token from `ufctl auth login`
local:
  organization_id: <org-id>
  server_id: <server-id>

If the file is absent the binary still starts; only control-plane tools will fail at call time.

Environment overrides

Variable	Default	Purpose
UNDERLEAF_AGENT_PORT	2240	Local UA-K agent port
UNDERLEAF_DEPLOY_PORT	8080	Local deployment-engine port

Installation

Via deployment_engine (recommended)

The deployment engine will download and manage the binary automatically once the UMC entry is added to umcs/deployment_engine/umcs.yaml.

Manual

Download the binary for your platform from the releases page and place it in ~/.underleaf/bin/:

chmod +x ~/.underleaf/bin/mcp-server-serve

IDE configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "underleaf": {
      "command": "/Users/<you>/.underleaf/bin/mcp-server-serve"
    }
  }
}

VS Code (GitHub Copilot Chat)

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "underleaf": {
      "type": "stdio",
      "command": "/Users/<you>/.underleaf/bin/mcp-server-serve"
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "underleaf": {
      "command": "/Users/<you>/.underleaf/bin/mcp-server-serve"
    }
  }
}

Development

# Build
make build

# Run (smoke test — paste JSON-RPC manually on stdin)
make run

# Test
make test

# Tidy dependencies
make deps

Architecture

cmd/serve/main.go           ← Entry point: wires config, clients, MCPServer
internal/config/            ← Reads ~/.underleaf/config.yaml
internal/httpclient/        ← Generic HTTP client (shared by all tool groups)
internal/tools/             ← One file per resource group (cluster, servers, …)
internal/registry/          ← Aggregates all tool groups → registers with MCPServer