Skip to content
Docs/MCP Integration

Model Context Protocol (MCP)

Give agents real-time access to your project memory through the Model Context Protocol.

What is the vem MCP Server?

The @vemdev/mcp-server package allows AI clients (like Claude Desktop or Cursor) to call tools that read and write directly to your local.vem/ files and search the cloud index.

@vemdev/mcp-server on npm

Start the server with npx:

npx @vemdev/mcp-server@latest --api-key nk_your_key_here

Authentication

Get your API key from app.vem.dev → Settings → API Keys. There are three ways to provide it, in priority order:

1. VEM_API_KEY environment variable (highest priority)

VEM_API_KEY=nk_your_key_here npx @vemdev/mcp-server@latest

Always overrides any key stored in config — ideal for CI environments.

2. --api-key flag (recommended for MCP hosts)

npx @vemdev/mcp-server@latest --api-key nk_your_key_here

Saves the key to ~/.vem/config.json for reuse on subsequent starts.

3. vem login CLI

If you already use the VEM CLI and have logged in, the MCP server picks up the saved key automatically from ~/.vem/config.json.

Available Tools

get_active_tasks

Retrieve tasks from project memory. Defaults to active (non-done) tasks; pass status: "done" or status: "all" to include completed tasks.

statustodo|in-progress|done|alloptional

get_task_details

Get the full details of a single task including its subtasks, context, and history.

idstringrequired

add_task

Create a new task in project memory with optional validation steps.

titlestringrequireddescriptionstringoptionalprioritylow|medium|high|criticaloptionaltypefeature|bug|chore|spike|enableroptionalparent_idstringoptionalvalidation_stepsstring[]optionalreasoningstringoptional

start_task

Transition a task to in-progress status.

idstringrequiredsession_idstringoptionalsourcecopilot|claude|gemini|cursor|windsurf|codexoptionalsession_summarystringoptional

complete_task

Mark a task as done with evidence, reasoning, and agent signature.

idstringrequiredevidencestringrequiredreasoningstringrequired

update_task

Update a task's status (start, block, unblock), priority, or other fields.

idstringrequiredstatustodo|in-progress|blockedoptionalprioritylow|medium|high|criticaloptionalreasoningstringoptionalblocked_reasonstringoptionalblocked_bystring[]optionalvalidation_stepsstring[]optional

delete_task

Soft-delete a task from project memory with an optional reasoning note.

idstringrequiredreasoningstringoptional

get_task_context

Read the ephemeral scratchpad attached to a specific task (task_context).

idstringrequired

update_task_context

Set, append to, or clear the ephemeral scratchpad for a task to persist agent working notes. Supports three operations: set (replace), append (add), and clear (remove).

idstringrequiredoperationset|append|clearrequiredtextstringoptional

get_subtasks

List the direct children (subtasks) of a given parent task.

parent_idstringrequired

get_context

Read CONTEXT.md and CURRENT_STATE.md, prepended with the Agent Constitution if configured. Always call this at the start of a session to load full project context.

update_current_state

Overwrite the CURRENT_STATE.md file with a new summary of in-progress work and next steps.

contentstringrequired

search_memory

Semantic search over project memory via the cloud API. Requires a valid VEM_API_KEY; returns an error if not configured.

querystringrequired

ask_question

Ask a natural-language question against project memory — commits, diffs, tasks, and code.

questionstringrequiredpathstringoptional

add_decision

Record an architectural decision (ADR) with optional task linking.

titlestringrequiredcontextstringrequireddecisionstringrequiredrelated_tasksstring[]optional

list_decisions

List all recorded architectural decisions for the project.

limitnumberoptional

get_changelog

Read recent changelog entries to understand what work has been done.

limitnumberoptional

sync_push

Push local VEM snapshot to the cloud. Syncs tasks, context, decisions, and changelog to the remote project.

forcebooleanoptionaldry_runbooleanoptional

sync_pull

Pull the latest verified snapshot from the cloud into the local .vem/ directory.

forcebooleanoptional

apply_vem_update

Apply a structured vem_update block to local memory artifacts (context, state, changelog, decisions, tasks).

current_statestringoptionalcontextstringoptionalchangelog_appendstring|string[]optionaldecisions_appendstring|string[]optionaltasksobject[]optional

list_agent_sessions

List recent agent sessions (Copilot CLI, Claude CLI, Gemini CLI, Cursor, Windsurf, and Codex) for the current repository. Call this at the start of a session to see what previous sessions worked on — including their summaries, intents, and first user messages.

limitnumberoptionalbranchstringoptionalsourcesstring[]optional

save_session_stats

Record session statistics (duration, turns, tool calls, model usage) onto the active task when finishing a session.

task_idstringrequiredsession_idstringrequiredsourcestringoptional

get_cycle_context

Fetch the current work cycle (sprint) context including goals and included tasks.

get_flow_metrics

Retrieve flow metrics for the project — task throughput, cycle times, and completion trends.

task_idstringoptional

validate_cycle

Run pre-flight validation for a cycle: checks task completeness, evidence quality, blocked tasks, and sensor results. Use before closing a cycle.

cycle_idstringrequiredskip_sensorsbooleanoptional

get_cycle_health

Get a health snapshot for a cycle: task status breakdown, appetite progress, and last validation result.

cycle_idstringoptional

get_cycle_retrospective

Generate or retrieve a retrospective for a cycle. Returns completed/deferred tasks, decisions made, and validation summary.

cycle_idstringrequired

get_constitution

Read the Agent Constitution — immutable principles all agents must follow in this project.

get_context_index

Get a lightweight table of contents for all project memory: CONTEXT.md sections, task count, decision count, and recent changelog entries.

get_context_section

Fetch a specific section of project memory (context, current_state, tasks, decisions, changelog, constitution) without loading everything.

sectioncontext|current_state|tasks|decisions|changelog|constitutionrequired

list_skills

List all skills installed in this project from skills-lock.json. Use this to discover available slash commands.

get_task_spec

Get the acceptance criteria (spec) for a task — the concrete list of criteria that define when the task is done.

task_idstringrequired

set_task_spec

Set the acceptance criteria (spec) for a task. Each criterion should be a testable, concrete statement.

task_idstringrequiredcriteriastring[]required

deposit_plan

Deposit a plan document (findings, recommendations, next steps) into the project for human review. Use at the end of a research or planning run.

titlestringrequiredbodystringrequiredtask_run_idstringoptional

list_plans

List plans for the current project. Returns plan summaries with id, title, status, source, and date.

statuspending|approved|rejected|doneoptional

get_plan

Get the full content of a specific plan by its ID.

plan_idstringrequired

run_feedback_sensors

Run one or all feedback sensors (lint, typecheck, test, etc.) configured in .vem/sensors.json. Use before committing or validating work.

sensorsstring[]optional

Recommended session protocol

At the start of every session:

  1. get_context — Load CONTEXT.md + CURRENT_STATE.md to understand project state.
  2. list_agent_sessions — See what previous sessions worked on to avoid duplicating effort.
  3. get_active_tasks — Find open work to pick up or continue.

When finishing a session:

  1. update_current_state — Write a brief summary of what was done and what comes next.
  2. apply_vem_update — Persist context, changelog, decisions, and task updates atomically.
  3. sync_push — Push the local snapshot to the cloud for cross-session continuity.

Review / validation runs and vem_review

When running in validation or review mode the runner scans agent output for a vem_review block and persists any issues to the project dashboard. Omitting the block generates an info-level finding "No review output detected".

Output the block as a fenced code block at the end of your session:

```vem_review
{
  "task_id": "TASK-042",
  "overall_status": "pass",
  "summary": "All validation steps pass; no blocking issues found.",
  "issues": [
    {
      "severity": "warning",
      "title": "Missing test coverage for edge case",
      "description": "The null-input path in parseConfig() is not covered.",
      "file_path": "src/config.ts",
      "line_number": 87,
      "suggestion": "Add a unit test for parseConfig(null)."
    }
  ]
}
```

For a clean pass with no issues, set overall_status: "pass" and pass an empty issues array. Severity values high/critical are normalized to error, medium → warning, low → info.

Task Lifecycle with update_task

Use update_task to manage task status throughout the development lifecycle:

  • in-progress - Start working on a task
  • blocked - Mark as blocked (reasoning required)
  • todo - Unblock a task
// Start working on a task
{
  "id": "TASK-003",
  "status": "in-progress",
  "reasoning": "Beginning implementation"
}

// Block a task
{
  "id": "TASK-003",
  "status": "blocked",
  "reasoning": "Waiting for API endpoint",
  "blocked_by": ["TASK-001"]
}

Completing tasks with complete_task

When creating tasks via MCP, you can define validation_steps (for example, pnpm build or pnpm test). Agents must confirm those steps when completing the task.

Use complete_task to mark a task done. The required parameters are id, evidence (a string describing what was done), and reasoning (why the task is complete).

{
  "id": "TASK-123",
  "evidence": "pnpm build && pnpm test passed",
  "reasoning": "All validation steps pass; feature is working as specified."
}

Recording Decisions with add_decision

Use add_decision to record architectural decisions (ADRs) directly from agents. Link decisions to tasks to track what motivated or implements them.

{
  "title": "Use Zod for validation",
  "context": "Need runtime type checking for API inputs",
  "decision": "Chose Zod over Yup for better TypeScript inference",
  "related_tasks": ["TASK-042", "TASK-043"]
}

Decisions are stored in .vem/decisions/ with timestamp-based filenames for chronological ordering.

Reading Recent Changes with get_changelog

Use get_changelog to understand what work has been done recently without searching through git history.

{
  "limit": 10  // Optional, defaults to 10, max 50
}

Returns recent changelog entries sorted by date descending, helping agents avoid duplicate work and understand project progress.

Claude Desktop Setup

Add the following to your Claude Desktop config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "vem": {
      "command": "npx",
      "args": ["-y", "@vemdev/mcp-server@latest", "--api-key", "nk_your_key_here"]
    }
  }
}

Cursor Setup

Add the following to .cursor/mcp.json:

{
  "mcpServers": {
    "vem": {
      "command": "npx",
      "args": ["-y", "@vemdev/mcp-server@latest", "--api-key", "nk_your_key_here"]
    }
  }
}

VS Code Setup

Add the following to .vscode/mcp.json. VS Code requires a servers wrapper key:

{
  "servers": {
    "vem": {
      "command": "npx",
      "args": ["-y", "@vemdev/mcp-server@latest", "--api-key", "nk_your_key_here"]
    }
  }
}

GitHub Copilot (VS Code)

Add the following to .vscode/mcp.json. GitHub Copilot uses the same servers-wrapped format as VS Code. See the VS Code Copilot MCP docs for full details.

{
  "servers": {
    "vem": {
      "command": "npx",
      "args": ["-y", "@vemdev/mcp-server@latest", "--api-key", "nk_your_key_here"]
    }
  }
}

Windsurf Setup

Add the following to ~/.codeium/windsurf/mcp_config.json:

{
  "vem": {
    "command": "npx",
    "args": ["-y", "@vemdev/mcp-server@latest", "--api-key", "nk_your_key_here"]
  }
}

Environment Variables

All environment variables are optional unless otherwise noted. Use them when you prefer not to pass flags, or for CI / headless runs.

VariableDefaultDescription
VEM_API_KEY—API key (alternative to the --api-key flag)
VEM_API_URLhttps://api.vem.devVEM API endpoint — only set this if you self-host
VEM_AGENT_NAMEmcp-agentAgent name shown in the vem dashboard
VEM_ACTIVE_TASK—Pre-set the active task ID (e.g. TASK-042) for headless or CI runs
VEM_TASK_RUN_ID—Task run ID passed to cloud APIs (e.g. when calling ask_question)

Next steps

Agent Protocols

Learn the manual exchange format for agents without MCP.

CLI Reference

Control your project memory from the terminal.