Evc Mesh MCP

EVC Mesh MCP Server

Tasks, comments, shared memory and handoffs for teams of people and AI agents, over MCP.

EVC Mesh is an open-source task manager built for teams where people and AI agents work side by side. This Model Context Protocol server connects your agent to a Mesh workspace: it can pick up assigned tasks, check out work, comment, move tasks through your workflow, hand off to teammates, and keep decisions in shared project memory.

Two tool profiles: core (34 tools, for everyday task work) and full (84 tools, including recurring tasks, docs and workspace admin). Every tool is marked read-only or write, so clients can ask before changing anything.

You need a Mesh workspace and an agent key from it. Mesh is self-hosted (Apache-2.0, docker compose setup in the evc-mesh repository). Set MESH_API_URL to your instance and MESH_AGENT_KEY to the agent's key. Workspaces on the hosted instance are by invitation.

Works with Cursor, Cline, OpenClaw and other MCP clients.

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 .

Docker

docker run -i --rm \

-e MESH_API_URL \ -e MESH_AGENT_KEY \ ghcr.io/entire-vc/evc-mesh-mcp

-i is required — the server speaks MCP over stdio, and Docker only wires up stdin when the container runs interactively. The image starts with the core profile; add -e MESH_MCP_PROFILE=full for every tool (see Tool Profiles below). The image is published for linux/amd64 and linux/arm64 from Dockerfile in this repo on every tagged release (docs/RELEASING.md).

Tool Profiles

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

Set via MESH_MCP_PROFILE environment variable. Default: full for the binary, core for the Docker image (-e MESH_MCP_PROFILE=full switches it).

Configuration

Running without credentials

In stdio mode the server also starts when MESH_AGENT_KEY is not set. It then answers initialize and tools/list as usual, and every tool call returns instructions for setting MESH_API_URL and MESH_AGENT_KEY. This lets MCP clients and catalogs inspect the tool list before you have a key. If a key is set but authentication fails at startup (API unreachable, key rejected), the server keeps running: tools are listed, and each call retries authentication and returns the reason until it succeeds.

Tool annotations

Every tool declares the MCP hints readOnlyHint, destructiveHint, idempotentHint and openWorldHint, so clients can tell read-only tools (get_*, list_*, recall, search_docs, …) from ones that change or remove data (update_*, move_task, forget, …).

Client metrics

Each initialize is logged with the client's clientInfo.name and version, and counted in the Prometheus metric mesh_mcp_initialize_total{client,profile} (exposed on /metrics in SSE mode; client names are normalised and capped).

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:

The same process also serves the Streamable HTTP transport (stateless, one agent key per request, sent in the Authorization: Bearer or X-Agent-Key header — the query parameter is refused there):

Authentication per connection via:

• Authorization: Bearer agk_... header
• X-Agent-Key: agk_... header
• ?agent_key=agk_... query parameter (SSE connect only)
• Authorization: Bearer mot_... — an OAuth access token issued by your Mesh instance (see below); the header only, never the query string, and on the Streamable HTTP endpoints only (SSE connections need an agent key)

OAuth (remote connectors)

Clients that sign users in with OAuth — remote-connector directories, MCP Inspector, editors that follow the MCP authorization spec — connect to the Streamable HTTP endpoints without a pre-shared key. Your Mesh instance is the authorization server (dynamic client registration, PKCE, user consent); this server is the resource server and does two things:

• Challenges. A request with no credential, or with an OAuth access token Mesh API rejects (expired, revoked, never issued), gets 401 and

  WWW-Authenticate: Bearer resource_metadata="https://mesh.example.com/.well-known/oauth-protected-resource/mcp", scope="mesh"

which is where a client starts the authorization flow. A rejected agent key keeps answering 403. Only a verdict from Mesh API (a 4xx other than 408/429) makes a token invalid: if Mesh API cannot be reached or answers with an error that says nothing about the token (5xx, 429), the answer is 503 with Retry-After, so a valid token is not thrown away over an outage.

• Serves the metadata (RFC 9728) at the well-known path derived from each endpoint's URL:

  {

"resource": "https://mesh.example.com/mcp", "authorization_servers": ["https://mesh.example.com"], "scopes_supported": ["mesh"], "bearer_methods_supported": ["header"] }

resource is MESH_MCP_PUBLIC_URL (trailing slash, query and fragment removed; /core appended for the core profile), so set it to the URL your users paste into the client. The authorization server defaults to that URL's origin; override it with MESH_MCP_OAUTH_ISSUER.

An OAuth token acts as a connector agent in the workspace the user chose when they granted access, with that agent's permissions — the same tools, the same permission model as an agent key. Verified tokens are cached for a minute (MESH_MCP_OAUTH_CACHE_TTL_SEC). The per-IP budget (MESH_MCP_AUTH_FAIL_RPM) is spent by *rejected* tokens, not by verifications, so many users behind one address are not throttled by their own token refreshes. The token is not audience-bound: any valid access token from your Mesh instance is accepted, which is the intent while the authorization server and this server belong to the same deployment. Agent keys (agk_...) in Authorization or X-Agent-Key work exactly as before, and stdio mode is unaffected.

Your reverse proxy must send /.well-known/oauth-protected-resource* to this server instead of the web app's catch-all: a single-page app answers every unknown path with 200 text/html, which a client cannot tell from missing metadata.

Agent Context Protocol (ACP)

At session start, follow these 5 steps in order:

1. heartbeat(status="online")              → register as alive

1. get_project_knowledge(project_id) → load accumulated decisions & conventions
2. get_my_rules(project_id) → understand constraints
3. get_context(project_id) → see recent activity + p