Miadi MCP Server

A Model Context Protocol (MCP) server that exposes the Miadi Three-Pathway Agent System as tools for Claude, VS Code, Copilot, and any MCP-compatible client.

Version: 1.4.0 | Tools: 103 across 17 categories | SDK: Official MCP TypeScript SDK

Quick Start

Install & Run Locally

npx miadi-mcp-server

Or clone and build:

cd mcp_server
npm install
cp .env.example .env   # Configure EH_TOKEN and EH_API_URL
npm run build
npm start              # stdio transport (local clients)
npm run start:remote   # HTTP transport (remote clients)

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | EH_TOKEN | Yes | Miadi API authentication token | | EH_API_URL | Yes | Miadi API base URL | | MCP_PORT | No | HTTP server port (default: 3330) | | MIADI_TOOLS_ROLE | No | Predefined role for tool selection | | MIADI_TOOLS_ENABLED | No | Categories or tools to enable | | MIADI_TOOLS_DISABLED | No | Categories or tools to disable | | MIADI_HIDE_UNACCEPTABLE | No | Hide broken/partial tools (true/false) |

Client Configuration

Claude Desktop (Local)

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "miadi": {
      "command": "npx",
      "args": ["-y", "miadi-mcp-server"],
      "env": {
        "EH_TOKEN": "your_token",
        "EH_API_URL": "https://your-instance.com"
      }
    }
  }
}

Claude.ai (Remote)

1. Start the remote server:

   npm run start:remote

2. Expose via tunnel (ngrok, Cloudflare Tunnel, etc.):

   ./scripts/start-with-ngrok.sh

3. In Claude.ai Settings → Remote MCP Servers → Add:
   • URL: https://your-domain.example.com/mcp

VS Code / Copilot

In .vscode/settings.json or user settings:

{
  "mcp": {
    "servers": {
      "miadi": {
        "type": "http",
        "url": "https://your-domain.example.com/mcp"
      }
    }
  }
}

Or for local stdio:

{
  "mcp": {
    "servers": {
      "miadi": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "miadi-mcp-server"],
        "env": {
          "EH_TOKEN": "your_token",
          "EH_API_URL": "https://your-instance.com"
        }
      }
    }
  }
}

Any MCP Client (HTTP)

The remote server exposes a standard MCP endpoint:

| Method | Path | Purpose | |--------|------|---------| | POST | /mcp | MCP JSON-RPC endpoint | | GET | /health | Health check |

# Test connectivity
curl https://your-domain.example.com/health

# MCP initialize
curl -X POST https://your-domain.example.com/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

Self-Hosting the Remote Server

With ngrok

# Set your ngrok domain (optional)
export NGROK_DOMAIN=your-subdomain.ngrok-free.app

# Start server + tunnel
./scripts/start-with-ngrok.sh [port]

With Docker / Reverse Proxy

# Build and start
npm run build
MCP_PORT=3330 npm run start:remote

# Then proxy via nginx, Caddy, etc. to https://your-domain.com → localhost:3330

The server listens on 0.0.0.0:3330 by default. CORS is pre-configured for claude.ai and *.ngrok-free.app.

Tool Selection

Predefined Roles

| Role | Categories | Tools | |------|------------|-------| | developer | All 17 | ~103 | | storyteller | 7 narrative-focused | ~46 | | researcher | 7 analysis-focused | ~42 | | agent | 6 workflow-focused | ~30 | | administrator | 5 system categories | ~25 | | observer | Read-only tools | 18 | | minimal | memory + session | 15 |

MIADI_TOOLS_ROLE=storyteller

Category Selection

# Enable specific categories
MIADI_TOOLS_ENABLED=memory,session,ai

# Disable specific categories
MIADI_TOOLS_DISABLED=workflow,forge

# Combine role + overrides
MIADI_TOOLS_ROLE=researcher
MIADI_TOOLS_ENABLED=narrative-performance
MIADI_TOOLS_DISABLED=miadi-rag-execute-and-wait

17 Tool Categories

| Category | Tools | Purpose | |----------|-------|---------| | memory | 9 | Redis key-value operations, scanning, gathering | | session | 6 | Agent session lifecycle | | spiral | 8 | Spiral memory descent and search | | diary | 9 | Ceremonial diary with five-phase protocol | | storytelling | 8 | Story session management and generation | | live-story-monitor | 5 | Three-universe narrative dashboard | | capability | 3 | Dynamic capability resolution | | ai | 2 | OpenAI and generic AI requests | | workflow | 3 | GitHub event workflows | | forge | 3 | Forge state and glyph map | | stc | 7 | Story Tech Component charts | | narrative-performance | 4 | Text-to-audio performance | | data-structures | 9 | Lattices, redstones, cluster visualization | | rag | 4 | Research queries with Two-Eyed Seeing | | database-intelligence | 3 | System analytics and health | | integration | 11 | GitHub, Flowise, multiverse, cache | | narrative | 4 | Three-universe event analysis |

See ROLES.md for role definitions and TOOLS_REFERENCE.md for parameter documentation.

Limitations

Some tools have known issues — see TOOL_STATUS.md for per-tool status. Set MIADI_HIDE_UNACCEPTABLE=true to filter broken/partial tools from the available tools list. Non-developer roles enable this automatically.

License

MIT