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.8 | Tools: 103 across 17 categories | SDK: Official MCP TypeScript SDK

Quick Start

Install & Run Locally

```bash npx @miadi/mcp ```

Or clone and build:

```bash 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):

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

Claude.ai (Remote)

1. Start the remote server: ```bash npm run start:remote ```
2. Expose via tunnel (ngrok, Cloudflare Tunnel, etc.): ```bash ./scripts/start-with-ngrok.sh ```
3. In Claude.ai Settings → Connectors → Add Custom Connector:
   • Name: miadi
   • URL: https://your-domain.example.com/mcp

Authentication: The server requires a Bearer token on /mcp. By default it uses EH_TOKEN. To set a separate token: ```bash export MCP_AUTH_TOKEN=your-secret-token ```

Claude.ai sends the token via the Authorization header automatically when configured.

VS Code / Copilot

In .vscode/settings.json or user settings:

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

Or for local stdio:

```json { "mcp": { "servers": { "miadi": { "type": "stdio", "command": "npx", "args": ["-y", "@miadi/mcp"], "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 |

```bash

Health (no auth required)

curl https://your-domain.example.com/health

MCP initialize (Bearer token required)

curl -X POST https://your-domain.example.com/mcp
-H "Content-Type: application/json"
-H "Authorization: Bearer YOUR_TOKEN"
-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

```bash

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

```bash

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 | Description | Categories | Tools | |------|-------------|------------|-------| | architect | 🧠 System architecture & Forge (Mia) | 4 core | ~20 | | storyteller| 🌸 Narrative & Performance (Miette) | 4 core | ~25 | | keeper | 🌊 Memory & Wisdom (Tushell) | 3 core | ~20 | | operator | ⚙️ Workflow & Coordination | 3 core | ~20 | | analyst | 🔍 Research & Intelligence | 2 core | ~15 | | developer | 🛠️ Full system access | All 17 | ~103 | | minimal | 🌱 Core memory only | 1 category | ~10 |

```bash

Start with a specific role via CLI

./scripts/start-with-ngrok.sh --role storyteller

Or via environment variable

export MIADI_TOOLS_ROLE=architect ```

Category Selection

```bash

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