Connect AI Agents to EVC Mesh

EVC Mesh MCP Server

Model Context Protocol (MCP) server for EVC Mesh - a task management platform for coordinating humans and AI agents.

Connects AI agents (Claude Code, Cursor, Cline, OpenClaw, etc.) to EVC Mesh via MCP tools for task management, persistent memory, event publishing, and multi-agent coordination.

This is the actively developed copy. evc-mesh also ships an MCP server (./cmd/mcp, same internal/mcp tool set) that it builds and deploys itself - the two exist because Go's internal/ visibility rules mean one repo can't import the other's package, not because they're meant to diverge. New tools and fixes land here first.

Prerequisites

• Go 1.22+
• Running EVC Mesh instance
• Agent registered in Mesh with an API key (agk_...)

Installation

go install github.com/entire-vc/evc-mesh-mcp@latest

Or build from source:

git clone https://github.com/entire-vc/evc-mesh-mcp.git
cd evc-mesh-mcp
go build -o evc-mesh-mcp .

Tool Profiles

The MCP server supports two profiles to optimize context window usage:

Set via MESH_MCP_PROFILE environment variable. Default: full.

Configuration

Claude Code (stdio mode)

Add to your project's .mcp.json:

{
  "mcpServers": {
    "evc-mesh": {
      "command": "evc-mesh-mcp",
      "env": {
        "MESH_API_URL": "https://your-mesh-instance.example.com",
        "MESH_AGENT_KEY": "agk_your-workspace_your-key",
        "MESH_MCP_PROFILE": "core"
      }
    }
  }
}

Cursor

Add to Cursor MCP settings (Settings → MCP Servers):

{
  "evc-mesh": {
    "command": "evc-mesh-mcp",
    "env": {
      "MESH_API_URL": "https://your-mesh-instance.example.com",
      "MESH_AGENT_KEY": "agk_your-workspace_your-key",
      "MESH_MCP_PROFILE": "core"
    }
  }
}

SSE Mode (multi-agent, shared server)

For connecting multiple agents through a shared MCP endpoint:

MESH_API_URL=https://your-mesh-instance.example.com \
MESH_MCP_PORT=8081 \
evc-mesh-mcp --transport sse

SSE mode serves two profiles simultaneously on different paths:

Authentication per connection via:

• Authorization: Bearer agk_... header
• X-Agent-Key: agk_... header
• ?agent_key=agk_... query parameter

Agent Context Protocol (ACP)

At session start, follow these 5 steps in order:

1. heartbeat(status="online")              → register as alive
2. get_project_knowledge(project_id)       → load accumulated decisions & conventions
3. get_my_rules(project_id)                → understand constraints
4. get_context(project_id)                 → see recent activity + project knowledge
5. get_my_tasks()                          → check assigned work

At session end:

publish_event(type="summary", memory={persist: true})  → broadcast + persist
session_report(model, tokens_in, tokens_out)           → report metrics

MCP Tools - Core Profile (20)

ACP & Identity

Task Management

Communication

Memory

What recall guarantees about its result

limit is a hard bound. The response never contains more than limit items,
and total always equals the number of items actually returned. Nothing is added
to the page after it has been sized - not pinned rows, not graph-expanded
neighbours.

Rows that fail scope/tags/tags_any are dropped, never returned unmarked.
This holds regardless of how a row reached the result: ordinary retrieval, pinning,
or graph expansion. A pinned row is exempt from ranking, not from eligibility -
"pinned" means "do not let ranking bury this", not "show this to a caller who asked
for a different scope".

Graph neighbours are marked and bounded. With RECALL_GRAPH_ENABLED=true,
recall also runs a knowledge-graph expansion and folds in hop > 0 neighbours,
each carrying graph_boost: true and provenance: via:graph. They occupy at most
limit/4 of the page (at least 1 when limit >= 2, none when limit < 2) and take
its tail slots, displacing the weakest retrieval hits rather than being appended
on top. When expansion returns nothing usable, the page is exactly the base result -
the reserve is a ceiling, not a quota. graph_boost_count reports how many slots
were actually spent.

The reserve exists because base hits carry score (RRF across the retrieval arms)
and neighbours carry composite_score from a separate traversal - different fields
on different scales. Sorting the union on a common key does not balance them; in
practice every observed neighbour ranks below every base hit, so a naive merge-sort
would silently disable graph boost. The reserve makes that trade explicit and
tunable.

Presets never overrule you. recall classifies the query and may apply a
profile (e.g. multi-session widens the page). A profile only fills in parameters you
did not supply; an explicit limit always wins.

Utility

MCP Tools - Full Profile (adds 25 more)

Additional Task Tools

Comments & Artifacts

Event Bus

Agent & Team

Governance & Config

Recurring Tasks

Architecture

AI Agent (Claude Code / Cursor / Cline / OpenClaw)
    ↕ MCP (stdio or SSE)
EVC Mesh MCP Server (core or full profile)
    ↕ REST API (HTTP)
EVC Mesh API Server
    ↕
PostgreSQL / Redis / NATS / S3

The MCP server is a lightweight proxy - it translates MCP tool calls into REST API requests. No direct database access needed.

Deploy checklist (prod server - no CI)

evc-mesh-mcp has no CD pipeline; deploys are manual. Mandatory order (per
CLAUDE-workflow.md §1b Deploy Discipline):
migrate (goose up) → binary swap → restart. Never swap the binary before migrations pass.

# 1. Build for the prod target
GOOS=linux GOARCH=amd64 go build -o evc-mesh-mcp .

# 2. Copy binary to prod
scp evc-mesh-mcp root@prod-host:/opt/evc-mesh-mcp/evc-mesh-mcp.new

# 3. On the prod host: run migrations FIRST, then swap binary
ssh root@prod-host

  # STEP 1 — Run evc-mesh DB migrations (mcp server reads the same DB).
  # goose CLI is not installed on the host — use the official docker image.
  # If this exits non-zero, STOP — do NOT swap the binary.
  DB_URL=$(grep ^DATABASE_URL /opt/evc-mesh/.env.prod | cut -d= -f2-)
  docker run --rm --network host \
    -v /opt/evc-mesh/migrations:/migrations \
    ghcr.io/pressly/goose:latest \
    goose -dir /migrations postgres "$DB_URL" up

  # STEP 2 — Swap binary (only after migrations succeed)
  mv /opt/evc-mesh-mcp/evc-mesh-mcp /opt/evc-mesh-mcp/evc-mesh-mcp.bak.$(date +%Y%m%d-%H%M%S)
  mv /opt/evc-mesh-mcp/evc-mesh-mcp.new /opt/evc-mesh-mcp/evc-mesh-mcp

  # STEP 3 — Restart
  sudo systemctl restart evc-mesh-mcp

  # STEP 4 — Smoke test
  curl -sf http://localhost:8081/health || echo "SMOKE FAILED"

evc-mesh-mcp does not run its own migrations - it relies on the evc-mesh API's
schema. The goose step above ensures the schema matches before the new binary serves traffic.

Local stdio binary - this repo also builds the tool your agent runs

The checklist above is for the SSE/HTTP prod server. This repo also builds the
binary a local stdio MCP client runs directly (no network deploy involved,
e.g. Claude Code's .mcp.json pointing at ~/bin/mesh-mcp). That path used to
be entirely manual - a merged fix could sit uninstalled indefinitely, looking
identical to "the feature doesn't exist" from inside an agent session (no
error, just an outdated tool). Where the fleet builds this way, a poll-based
watcher (not a GitHub-hosted runner - self-hosted CI runners on developer
machines are a known supply-chain risk this fleet avoids) rebuilds and
atomically installs the binary on origin/main changes, and the heartbeat
tool's mesh_version field (see the tools table above) lets a session confirm
which commit is actually installed without shelling out to the host.

Related

• evc-mesh - Core platform (API + Web UI)
• evc-mesh-openclaw-skill - OpenClaw skill (bash scripts)