EVOKORE Setup Guide

This guide covers everything you need to install EVOKORE-MCP, populate .env, configure child servers in mcp.config.json, register EVOKORE with one or more MCP clients, and validate the install. It also collects the full reference of EVOKORE_* environment variables in one place.

What this covers

• Prerequisites and install/build steps
• .env keys and the complete environment-variable reference
• permissions.yml and mcp.config.json walkthrough
• HTTP transport, RBAC, and async-boot configuration
• Client registration, the cross-CLI sync helper, and first-run validation

Prerequisites

Required

• Node.js >=20
• npm
• a built checkout of this repository

Required for current child/server options

• npx available on PATH for the configured github and fs child servers
• uv / uvx available on PATH if you want to use the optional elevenlabs child server or register VoiceMode separately

Optional credentials

• GITHUB_PERSONAL_ACCESS_TOKEN for GitHub operations
• ELEVENLABS_API_KEY for ElevenLabs proxy tools and VoiceSidecar
• SUPABASE_ACCESS_TOKEN for Supabase proxy tools
• OPENAI_API_KEY if you want to use VoiceMode

Install and build

npm ci
npm run build

The MCP runtime entrypoint is:

dist/index.js

Recommended operator preflight

If you are resuming ongoing repo work rather than doing a first install, run:

npm run repo:audit

This surfaces:

• current branch divergence from main
• active worktrees
• stale local/remote branch candidates
• open PR heads
• drift in operator-facing context, session, and root planning files

Environment and config files

.env

Start from .env.example.

Key values:

GITHUB_PERSONAL_ACCESS_TOKEN=your_github_pat_here
ELEVENLABS_API_KEY=your_elevenlabs_api_key_here
SUPABASE_ACCESS_TOKEN=your_supabase_access_token_here

# Optional discovery override (defaults to dynamic when unset)
EVOKORE_TOOL_DISCOVERY_MODE=dynamic

Common runtime toggles

The full reference is in Environment Variables Reference below. The most-used toggles are:

Important behavior:

• unresolved ${VAR} placeholders referenced by child-server env config fail fast for that child server
• other child servers continue booting
• discovery mode defaults to dynamic when unset

permissions.yml

permissions.yml controls proxied tool policy:

• allow
• require_approval
• deny

Current examples include:

• fs_read_file: allow
• fs_write_file: require_approval
• github_create_issue: require_approval

mcp.config.json

EVOKORE reads child-server definitions from mcp.config.json.

Current repo configuration:

{
  "skillRegistries": [],
  "servers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
      }
    },
    "fs": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./"]
    },
    "elevenlabs": {
      "command": "uvx",
      "args": ["elevenlabs-mcp"],
      "env": {
        "ELEVENLABS_API_KEY": "${ELEVENLABS_API_KEY}",
        "ELEVENLABS_MCP_OUTPUT_MODE": "both"
      }
    },
    "supabase": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server-supabase", "--read-only"],
      "env": {
        "SUPABASE_ACCESS_TOKEN": "${SUPABASE_ACCESS_TOKEN}"
      }
    },
    "ghidra_headless": {
      "disabled": true,
      "command": "${EVOKORE_RE_GHIDRA_HEADLESS_PYTHON}",
      "args": ["-m", "ghidra_headless_mcp", "--ghidra-install-dir", "${GHIDRA_INSTALL_DIR}"],
      "cwd": "${EVOKORE_RE_GHIDRA_HEADLESS_REPO}"
    },
    "reva": {
      "disabled": true,
      "command": "${EVOKORE_RE_REVA_PYTHON}",
      "args": ["-m", "reva_cli"],
      "cwd": "${EVOKORE_RE_REVA_REPO}"
    },
    "binary_analysis": {
      "disabled": true,
      "command": "${EVOKORE_RE_BINARY_MCP_PYTHON}",
      "args": ["-m", "src.server"],
      "cwd": "${EVOKORE_RE_BINARY_MCP_REPO}",
      "env": {
        "GHIDRA_HOME": "${GHIDRA_INSTALL_DIR}",
        "WINDBG_PATH": "${WINDBG_PATH}",
        "X64DBG_BRIDGE_URL": "${X64DBG_BRIDGE_URL}"
      }
    }
  }
}

Walkthrough:

• github, fs, and supabase are booted through npx
• elevenlabs is optional and booted through uvx
• supabase is optional and requires SUPABASE_ACCESS_TOKEN
• ghidra_headless, reva, and binary_analysis are disabled by default so the checked-in config stays safe on machines without the local RE toolchain
• child env values can interpolate shell environment variables via ${VAR} syntax
• child command, args, cwd, and url fields also support ${VAR} interpolation
• disabled child servers are skipped entirely before placeholder resolution, so optional local integrations can live in the shared config without generating startup noise
• skillRegistries configures remote skill registries for list_registry using { name, baseUrl, index } objects

Optional local reverse-engineering child servers

If you want EVOKORE to proxy your local reverse-engineering MCP stack, set the following environment variables:

GHIDRA_INSTALL_DIR=/absolute/path/to/ghidra
EVOKORE_RE_GHIDRA_HEADLESS_PYTHON=/absolute/path/to/ghidra-headless-mcp/.venv/bin/python
EVOKORE_RE_GHIDRA_HEADLESS_REPO=/absolute/path/to/ghidra-headless-mcp
EVOKORE_RE_REVA_PYTHON=/absolute/path/to/reverse-engineering-assistant/.venv/bin/python
EVOKORE_RE_REVA_REPO=/absolute/path/to/reverse-engineering-assistant
EVOKORE_RE_BINARY_MCP_PYTHON=/absolute/path/to/binary-mcp/.venv/bin/python
EVOKORE_RE_BINARY_MCP_REPO=/absolute/path/to/binary-mcp
WINDBG_PATH=/absolute/path/to/windbg
X64DBG_BRIDGE_URL=http://127.0.0.1:8765

Then set the corresponding disabled flags in mcp.config.json to false for the child servers you want to boot.

Current guidance:

• ghidra_headless: safe path for Ghidra 12.x headless analysis
• reva: stdio bridge to ReVa headless/Ghidra-backed workflows
• binary_analysis: binary-mcp for static, .NET, and debugger-assisted analysis
• ghidra-live / GhidraMCP GUI bridge is intentionally not wired here yet because the available plugin build is for Ghidra 11.3.2, while the current workstation is on Ghidra 12.0.4

HTTP transport for child servers

Child servers that expose an HTTP endpoint instead of stdio can be configured with:

{
  "servers": {
    "my-http-server": {
      "transport": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

EVOKORE uses StreamableHTTPClientTransport from the MCP SDK for HTTP-based child servers. All other child server features (prefixing, permissions, rate limiting) work identically.

Rate limiting

Add a rateLimit block to any server definition:

{
  "servers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "rateLimit": {
        "maxTokens": 10,
        "refillRate": 2,
        "refillIntervalMs": 1000
      }
    }
  }
}

• Algorithm: token bucket
• maxTokens: burst capacity (max calls before throttling)
• refillRate: tokens restored per interval
• refillIntervalMs: refill period in milliseconds
• Rate limiting is separate from error-triggered cooldown

HTTP transport authentication

When exposing EVOKORE-MCP over HTTP (instead of stdio), you can enable Bearer token authentication to protect the /mcp endpoint.

1. Set the environment variables in your .env:

   EVOKORE_AUTH_REQUIRED=true
   EVOKORE_AUTH_TOKEN=your-secret-token-here
   

2. All requests to /mcp must include the token:

   curl -X POST http://localhost:3000/mcp \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-secret-token-here" \
     -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
   

3. The /health endpoint is always unauthenticated (for load balancer probes):

   curl http://localhost:3000/health
   

Behavior notes:

• When EVOKORE_AUTH_REQUIRED is unset or false, no authentication is enforced (default).
• When EVOKORE_AUTH_REQUIRED=true but EVOKORE_AUTH_TOKEN is unset, all requests to protected endpoints are rejected and a warning is logged on startup.
• Unauthorized requests receive a 401 response with a JSON-RPC error body and WWW-Authenticate: Bearer header.
• Token comparison uses timing-safe equality to prevent timing attacks.

RBAC setup

1. Set EVOKORE_ROLE in your .env:

   EVOKORE_ROLE=developer
   

2. Role definitions live in permissions.yml under roles::

   • admin: default_permission: allow (full access)
   • developer: default_permission: require_approval with per-tool overrides for read operations
   • readonly: default_permission: deny with per-tool overrides for safe read operations

3. When EVOKORE_ROLE is unset, flat per-tool rules under rules: apply (the pre-RBAC behavior).

Async proxy boot

Child servers boot asynchronously in the background so the MCP handshake completes immediately. This means:

• Your client connects and receives the native tool list without waiting for child servers
• Proxied tools become available as each child server finishes booting
• Boot progress is emitted to stderr: "Proxy bootstrap complete" or "Background proxy bootstrap failed"
• Configure the boot timeout via EVOKORE_CHILD_SERVER_BOOT_TIMEOUT_MS (default: 30000ms)

If you need to point EVOKORE at another config file, set:

EVOKORE_MCP_CONFIG_PATH=/absolute/path/to/another-mcp.config.json

HTTP server mode

EVOKORE can also run as an HTTP server using the MCP StreamableHTTP transport. This enables remote access, multi-client connections, and load-balancer health checks.

Starting in HTTP mode

# Via environment variable
EVOKORE_HTTP_MODE=true node dist/index.js

# Via CLI flag
node dist/index.js --http

# With custom port and host
EVOKORE_HTTP_MODE=true EVOKORE_HTTP_PORT=8080 EVOKORE_HTTP_HOST=0.0.0.0 node dist/index.js

Endpoints

Health check

curl http://127.0.0.1:3100/health

Client connection example

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("http://127.0.0.1:3100/mcp")
);
const client = new Client({ name: "my-client", version: "1.0" });
await client.connect(transport);
const { tools } = await client.listTools();

Notes

• HTTP and stdio modes are mutually exclusive. A single process uses one transport.
• Default bind is 127.0.0.1 (loopback only). For remote access, set EVOKORE_HTTP_HOST=0.0.0.0 and place behind a reverse proxy with TLS.
• The server handles graceful shutdown on SIGTERM and SIGINT.
• All MCP features (tools, resources, prompts, HITL, RBAC) work identically over HTTP.

Client registration

Manual registration

Claude Desktop

Add this to your Claude Desktop MCP config:

{
  "mcpServers": {
    "evokore-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/EVOKORE-MCP/dist/index.js"]
    }
  }
}

Gemini CLI

gemini mcp add evokore-mcp node /absolute/path/to/EVOKORE-MCP/dist/index.js --scope user

Cursor

Register the same command:

node /absolute/path/to/EVOKORE-MCP/dist/index.js

Config sync helper

EVOKORE ships with a cross-CLI registration helper:

npm run sync:dry
npm run sync

Behavior summary:

• dry-run is the default safety mode
• npm run sync passes --apply
• existing evokore-mcp entries are preserved by default
• use --force only when you intentionally want to overwrite the current EVOKORE entry

Examples:

node scripts/sync-configs.js --apply
node scripts/sync-configs.js --apply --force
node scripts/sync-configs.js --apply claude-code cursor

Legacy vs dynamic discovery mode setup

Legacy mode

Best when:

• your client expects a full tool list
• you want the simplest compatibility posture
• you do not care about tool-list size

EVOKORE_TOOL_DISCOVERY_MODE=legacy

Dynamic mode

Best when:

• you want a smaller initial tool list
• you want session-scoped activation of proxied tools
• your workflow already uses discover_tools

EVOKORE_TOOL_DISCOVERY_MODE=dynamic

Dynamic mode notes:

1. Native EVOKORE tools remain visible.
2. Matching proxied tools become visible after discover_tools.
3. EVOKORE sends tools/list_changed best-effort.
4. Hidden proxied tools still remain callable by exact prefixed name.

Windows runtime notes

• EVOKORE remaps only npx to npx.cmd on Windows.
• EVOKORE does not rewrite uv or uvx.
• Verify uv --version and uvx --version in the same shell that launches your MCP host.

Voice-related setup choices

Use the right setup path for your goal:

See VOICE_AND_HOOKS.md for the full split between those systems.

First-run validation

Recommended validation order:

1. Build the project:

   npm run build
   

2. Confirm registration points to dist/index.js.

3. Start your MCP client and verify the server connects.

4. Use a safe tool like search_skills or discover_tools.

5. If using dynamic mode, run discover_tools and then refresh tools/list.

6. If using ElevenLabs, ensure ELEVENLABS_API_KEY is set before launch.

Useful targeted validations:

npx vitest run test-version-contract-consistency.js
npx vitest run test-tool-discovery-validation.js
npm run docs:check
npx vitest run test-windows-exec-validation.js
npm run repo:audit -- --json

For voice and hook paths:

npx vitest run test-voice-sidecar-smoke-validation.js
npx vitest run test-voice-sidecar-hotreload-validation.js
npx vitest run hook-e2e-validation.js

Environment Variables Reference

See .env.example for the authoritative list of variables and their defaults.

This section provides a grouped reference for every EVOKORE_* environment variable. Some variables also appear in the Common runtime toggles table above; they are included here for completeness within each logical group.

Core / Runtime

Session Storage

Webhooks

Plugins

Telemetry

Audit

Security

OAuth / Auth

HTTP Transport

Sandbox

Dashboard / WebSocket

Hooks

Speech-to-Text (STT)

Text-to-Speech (TTS)

If setup fails

Go to:

• USAGE.md
• TROUBLESHOOTING.md
• TESTING_AND_VALIDATION.md

See also

• Architecture — what you are installing, in module-level detail
• Tools and Discovery — the discovery-mode tradeoffs you are about to choose between
• Tool Discovery Profiles — per-profile token budgets
• HTTP Deployment — running EVOKORE over HTTP for remote and multi-client setups
• Voice and Hooks — VoiceSidecar, hook scripts, and the persona system

Last verified: 2026-05-20