Model Context Protocol (MCP)

Vreko integrates with AI coding assistants through the Model Context Protocol (MCP), enabling seamless context sharing for snapshots, risk detection, and learning capture.

Local MCP (Available Now)

100% Local, 100% Private Free

Vreko’s MCP integration works entirely on your machine. No cloud connectivity required. No data sent to Vreko servers.

Features:

• ✓ Snapshot management
• ✓ Task tracking with learnings
• ✓ Code validation
• ✓ Pattern enforcement
• ✓ Risk analysis (local)

Available to: All tiers (Free, Pro, Team, Enterprise)

Jump to Local MCP Setup →

Recommended Setup

# Or install via CLI
code --install-extension MarcelleLabs.vreko-vscode

npm install -g @vreko/cli
vreko tools configure --claude

vreko claude-sync

vreko login

Manual Setup (Advanced)

Continue

Configure in .continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "name": "vreko",
        "command": "vreko",
        "args": ["mcp", "--stdio"]
      }
    ]
  }
}

SOPR MCP Open-Source Library

Vreko’s MCP integration is powered by an internal implementation of the Service-Oriented Protocol Router (SOPR) pattern.

For teams who want to reuse that architecture directly, we publish the core server framework as an open-source NPM package:

• Library: @vreko-oss/sopr-mcp
• Source: vreko-oss/vreko-mcp

This library gives you:

• A SOPR-based MCP server factory (createSOPRServer) built around the same protocol → registry → tools → services layering used in Vreko
• First-class support for mode-based tools instead of a large, flat list of commands
• Extension points for routers, telemetry, and resilience, so you can plug in your own transport and analytics

Tip: Start with the library docs in the repository’s docs/ folder:

• docs/architecture.mdx – how the SOPR MCP server is wired internally
• docs/usage-sopr-mcp.mdx – how to build your own MCP server on top of it
• docs/diagrams.mdx – visual diagrams of the architecture and request flow

If you like how Vreko behaves inside your editor today, @vreko-oss/sopr-mcp is the foundation you can reuse to build similar MCP-powered workflows for your own tools.

Default Surface (Minimal)

Core Commands (5):

• PERCEIVE: pulse - workspace health check
• REASON: advise, guide - get recommendations and concrete plans
• ACT: vreko, check - task and validation
• REFLECT: snap_learn, snap_end - capture learnings

What you get:

• Clean, focused tool list for AI assistants
• Fast tool discovery and invocation
• Anthropic MCP best-practice compliance
• All essential Vreko workflows

Full Surface (Advanced)

Set VREKO_MCP_INTELLIGENCE_SURFACE=full to enable advanced tools:

Additional Tools (11):

• snap_violation - Report code violations for pattern learning
• learning_gc - Learning lifecycle management
• Intelligence Layer (5 tools): External context integration
  • vreko_validate_change, vreko_get_risk_score, vreko_query_patterns
  • vreko_get_context, vreko_suggest_rollback
• Learning Intelligence (5 tools): Pattern-based learning system
  • intelligence.capture, intelligence.patterns, intelligence.insights
  • intelligence.explain, intelligence.outcome

Enabling Full Surface:

// In your MCP config (e.g., ~/.cursor/mcp.json)
{
  "mcpServers": {
    "vreko": {
      "command": "npx",
      "args": ["@vreko/cli", "mcp", "--stdio"],
      "env": {
        "VREKO_MCP_INTELLIGENCE_SURFACE": "full"
      }
    }
  }
}

Use full surface when:

• You need proactive risk assessment with external context (GitHub, Sentry, Context7)
• You want pattern-based learning and detection
• You’re debugging complex production issues
• You need violation tracking and lifecycle management

1. pulse - Workspace Vitals (PERCEIVE)

Quick health check of workspace state before taking action.

Parameters:

{
  record_change?: string;  // Optional file path to record as change
}

Wire Response:

🫀|pulse:elevated|cpm:18|pressure:45|risk:M|changes:7|action:monitor

2. advise - Get Recommendations (REASON)

Get AI-powered advice on next steps based on current workspace state.

Parameters:

{
  task?: string;    // What you're about to do
  files?: string[]; // Files you plan to modify
  intent?: 'implement' | 'refactor' | 'debug' | 'test' | 'deploy';
}

Wire Response:

🧠|conf:65|rec:review|warn:2|learn:3|viol:1|hint:check_error_handling

3. vreko - Universal Entry Point (ACT)

Start tasks, get context, or quick check. This is the primary tool AI assistants should call first.

Parameters:

{
  mode?: 'start' | 'check' | 'context'; // or legacy: 's' | 'c' | 'x'
  task?: string;        // Task description (for start mode)
  files?: string[];     // Files to work on
  keywords?: string[];  // Keywords for learning retrieval
  intent?: 'implement' | 'debug' | 'refactor' | 'review' | 'explore';
  thorough?: boolean;   // Enable 7-layer validation (check mode)
  compact?: boolean;    // Use compact wire format
  goal?: {              // Goal for task completion validation
    metric: 'bundle' | 'performance' | 'coverage';
    target: number;
    unit: string;
  };
}

Modes:

• start (or s): Start a task, creates snapshot, loads learnings
• check (or c): Quick validation of files
• context (or x): Get current context without starting a task

Usage Example:

// AI assistant starts a task
await mcp.call('vreko', {
  mode: 'start',
  task: 'Refactor authentication module',
  files: ['src/auth.ts', 'src/config.ts'],
  intent: 'refactor'
});

4. check - Code Validation (ACT)

Validate code against patterns, run builds, check for issues.

Parameters:

{
  mode?: 'quick' | 'full' | 'patterns' | 'build' | 'impact' | 'circular'
       | 'docs' | 'learnings' | 'architecture' | 'trace' | 'security'
       | 'coverage' | 'orphans' | 'health';
  files?: string | string[];  // Files to check
  diff?: 'staged' | 'changed' | 'uncommitted'; // Auto-detect from git
  code?: string;              // Code to validate (for patterns mode)
  tests?: boolean;            // Run tests
  compact?: boolean;          // Use compact wire format
}

Modes (14 total):

• quick: Fast TypeScript + lint check (default) ⚡ RECOMMENDED
• full: Comprehensive 7-layer validation 🎯 PRODUCTION READY
• patterns: Pattern-only style compliance
• build: Build verification (runs pnpm build)
• impact: Change impact analysis with risk scoring
• circular: Circular dependency detection
• docs: Documentation freshness check
• learnings: Learning tier maintenance and stats
• architecture: Layer dependency validation
• trace: ❌ NOT YET IMPLEMENTED - Returns error message. Use quick or full instead.
• security: Secret detection and threat scanning
• coverage: Test coverage analysis
• orphans: Find orphan files and skipped tests
• health: MCP server diagnostics

5. snap_end - Complete Task (REFLECT)

Complete a task and capture learnings.

Parameters:

{
  outcome?: 'completed' | 'abandoned' | 'blocked';
  learnings?: string[];   // Key learnings from this task
  notes?: string;         // Additional completion notes
  efficiency?: {          // Your estimate of session efficiency
    saved?: string;       // Tokens saved (e.g., '~15K')
    prevented?: string;   // Mistakes avoided (e.g., '2 - wrong layer')
    helped?: string;      // What context helped (e.g., 'auth patterns')
  };
  survey?: {              // Optional self-assessment (helps improve Vreko)
    patterns_used?: number;      // How many patterns applied
    pitfalls_avoided?: number;   // How many mistakes avoided
    helpfulness?: number;        // Rating 1-5
    unhelpful_count?: number;    // Count of unhelpful suggestions
  };
  compact?: boolean;      // Use compact wire format
}

Wire Response:

🦎|E|status:OK|learn:2L|files:3F|lines:+45-12

6. snap_learn - Capture Learning (REFLECT)

Capture mid-session learnings for future reference. Use this mid-task for immediate learnings (vs snap_end for end-of-task summary).

Parameters:

{
  trigger: string;  // REQUIRED: What situation triggers this learning
  action: string;   // REQUIRED: What to do when triggered
  type?: 'pattern' | 'pitfall' | 'efficiency' | 'discovery' | 'workflow';
  source?: string;  // Where this learning originated
  compact?: boolean;
}

Learning Types:

• pattern: Something that worked well (“When doing X, always do Y”)
• pitfall: Mistake to avoid (“Never do X because Y happens”)
• efficiency: Token/time optimization (“Use X instead of Y”)
• discovery: New codebase knowledge (“File X handles Y”)
• workflow: Process improvement (“Better way to do X”)

Wire Response:

🦎|L|status:OK|id:learn_abc123|type:pattern

Usage Example:

await mcp.call('snap_learn', {
  trigger: 'modifying auth middleware',
  action: 'always validate session before token refresh',
  type: 'pitfall'
});

7. snap_violation - Report Violation (REFLECT)

Report a mistake for pattern learning. Use for actual bugs/errors (vs snap_learn pitfall for potential mistakes).

Parameters:

{
  type: string;        // REQUIRED: Violation category (e.g., 'silent_catch')
  file: string;        // REQUIRED: File where violation occurred
  description: string; // REQUIRED: What went wrong
  reason?: string;     // Why it happened (optional)
  prevention: string;  // REQUIRED: How to prevent in future
  compact?: boolean;
}

Auto-Escalation:

• 1st time: Recorded and tracked
• 3rd time: Promoted to pattern (prevents future occurrences)
• 5th time: Flagged for automation

Wire Response:

🦎|V|status:OK|type:silent_catch|count:3|promote:PROMOTED

Usage Example:

await mcp.call('snap_violation', {
  type: 'silent_catch',
  file: 'src/auth.ts',
  description: 'Catch block swallowed error without logging',
  reason: 'Rushed implementation, forgot logging',
  prevention: 'Always log in catch blocks with context'
});

Intelligence Layer Tools (Advanced)

The Intelligence Layer transforms Vreko from reactive protection to proactive prevention:

Before: AI makes change → Vreko snapshots it → User restores if broken

After: AI proposes change → Vreko evaluates against context → Informed decision before damage

Prerequisites

Intelligence Layer tools require external MCP server connections:

• GitHub MCP (@modelcontextprotocol/server-github) - Commit history, PR discussions, issue references
• Context7 MCP - API documentation validation, deprecation warnings
• Sentry MCP (@modelcontextprotocol/server-sentry) - Error tracking, stacktraces, failure patterns

1. vreko_validate_change - Proactive Change Validation

Validate file changes against aggregated external context before they’re applied.

Parameters:

{
  files: Array<{           // Files to validate
    path: string;
    content?: string;      // New content (optional)
    diff?: string;         // Git diff (optional)
  }>;
  context?: {
    intent?: string;       // Why this change is being made
    relatedIssues?: string[]; // GitHub issue references
  };
}

Response:

{
  validationResult: {
    overallRisk: number;   // 0-10 risk score
    riskLevel: 'low' | 'medium' | 'high' | 'critical';
    findings: Array<{
      file: string;
      type: 'security' | 'deprecation' | 'pattern_violation' | 'error_prone';
      severity: 'low' | 'medium' | 'high' | 'critical';
      message: string;
      source: 'github' | 'sentry' | 'context7' | 'local';
      confidence: number; // 0-100
    }>;
    recommendation: 'proceed' | 'review' | 'block';
    context: {
      recentErrors?: number;     // From Sentry
      relatedCommits?: number;   // From GitHub
      deprecationWarnings?: number; // From Context7
    };
  };
}

Wire Response:

🔍|V|score:45|level:medium|findings:3|rec:review|src:github+sentry

Usage Example:

// AI assistant validates before applying changes
const validation = await mcp.call('vreko_validate_change', {
  files: [{
    path: 'src/auth.ts',
    content: '// proposed new content...'
  }],
  context: {
    intent: 'Add JWT token refresh logic',
    relatedIssues: ['#123']
  }
});

if (validation.validationResult.recommendation === 'block') {
  console.warn('High risk detected - review required');
}

2. vreko_get_risk_score - Weighted Risk Assessment

Get comprehensive risk score with weighted factors from multiple sources.

Parameters:

{
  files: string[];         // File paths to analyze
  includeContext?: boolean; // Include full context details
}

Response:

{
  riskScore: number;       // 0-10 weighted score
  riskLevel: 'low' | 'medium' | 'high' | 'critical';
  factors: Array<{
    source: 'github' | 'sentry' | 'context7' | 'local';
    weight: number;        // 0-1 contribution to score
    score: number;         // 0-10 for this factor
    reason: string;
  }>;
  recommendation: string;
  confidence: number;      // 0-100 overall confidence
}

Wire Response:

🎯|R|score:67|level:high|factors:4|conf:85|rec:snapshot_first

Usage Example:

const risk = await mcp.call('vreko_get_risk_score', {
  files: ['src/payment.ts', 'src/api.ts'],
  includeContext: true
});

console.log(`Risk: ${risk.riskLevel} (${risk.riskScore}/10)`);
risk.factors.forEach(f => {
  console.log(`- ${f.source}: ${f.score} (weight: ${f.weight})`);
});

3. vreko_query_patterns - Pattern Database Query

Query Vreko’s patterns, violations, and learnings database.

Parameters:

{
  query: string;           // Search query
  type?: 'pattern' | 'violation' | 'learning' | 'all';
  filters?: {
    files?: string[];      // Filter by file patterns
    severity?: string[];   // Filter by severity
    since?: string;        // ISO date - patterns since date
  };
  limit?: number;          // Max results (default: 10)
}

Response:

{
  results: Array<{
    type: 'pattern' | 'violation' | 'learning';
    id: string;
    trigger: string;       // When this applies
    action: string;        // What to do
    occurrences: number;   // How many times seen
    lastSeen: string;      // ISO date
    confidence: number;    // 0-100
    relatedFiles: string[];
  }>;
  total: number;
  query: string;
}

Wire Response:

🔎|P|results:7|type:violation|query:auth|conf:92

Usage Example:

// Check for known auth-related pitfalls
const patterns = await mcp.call('vreko_query_patterns', {
  query: 'authentication',
  type: 'violation',
  filters: { severity: ['high', 'critical'] }
});

patterns.results.forEach(p => {
  console.log(`⚠️ ${p.trigger} → ${p.action}`);
});

4. vreko_get_context - Aggregated External Context

Get comprehensive context from all integrated external sources.

Parameters:

{
  files: string[];         // Files to get context for
  sources?: Array<'github' | 'sentry' | 'context7' | 'local'>; // Filter sources
  depth?: 'shallow' | 'deep'; // Context depth
}

Response:

{
  context: {
    github?: {
      recentCommits: Array<{...}>;
      relatedPRs: Array<{...}>;
      issues: Array<{...}>;
    };
    sentry?: {
      recentErrors: Array<{...}>;
      errorFrequency: number;
      affectedUsers: number;
    };
    context7?: {
      apiDocs: Array<{...}>;
      deprecations: Array<{...}>;
      versionInfo: {...};
    };
    local?: {
      snapshots: number;
      changeVelocity: number;
      aiDetectionSignals: Array<{...}>;
    };
  };
  aggregatedAt: string;    // ISO timestamp
  sources: string[];       // Active sources
}

Wire Response:

🌐|C|sources:3|commits:12|errors:5|docs:8|depth:deep

Usage Example:

const context = await mcp.call('vreko_get_context', {
  files: ['src/auth.ts'],
  sources: ['github', 'sentry'],
  depth: 'deep'
});

if (context.context.sentry?.errorFrequency > 10) {
  console.warn('High error rate detected in this file');
}

5. vreko_suggest_rollback - Intelligent Restore Suggestions

Get restore suggestions based on failure patterns and context.

Parameters:

{
  reason?: string;         // Why restore is needed
  files?: string[];        // Specific files to consider
  includeAnalysis?: boolean; // Include detailed analysis
}

Response:

{
  suggestions: Array<{
    snapshotId: string;
    timestamp: string;
    reason: string;
    confidence: number;    // 0-100
    filesAffected: string[];
    riskOfRestore: 'low' | 'medium' | 'high';
    relatedContext: {
      commitsBetween?: number;
      errorsSince?: number;
    };
  }>;
  recommended?: string;    // Recommended snapshot ID
  analysis?: {             // If includeAnalysis: true
    currentState: {...};
    targetState: {...};
    impact: {...};
  };
}

Wire Response:

🔄|RB|suggestions:3|recommended:snap_abc|conf:88|risk:low

Usage Example:

const restore = await mcp.call('vreko_suggest_rollback', {
  reason: 'Critical error after auth refactor',
  files: ['src/auth.ts'],
  includeAnalysis: true
});

const best = restore.suggestions[0];
console.log(`Suggest restoring to: ${best.snapshotId}`);
console.log(`Confidence: ${best.confidence}%`);
console.log(`Risk: ${best.riskOfRestore}`);

Setup External MCP Servers

# Install GitHub MCP server
npm install -g @modelcontextprotocol/server-github

# Configure in MCP settings
# Add to your AI assistant's MCP config:
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

# Install Sentry MCP server
npm install -g @modelcontextprotocol/server-sentry

# Configure in MCP settings
{
  "mcpServers": {
    "sentry": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-sentry"],
      "env": {
        "SENTRY_AUTH_TOKEN": "your_token_here",
        "SENTRY_ORG": "your-org",
        "SENTRY_PROJECT": "your-project"
      }
    }
  }
}

# Install Context7 MCP (requires subscription)
npm install -g @context7/mcp-server

# Configure in MCP settings
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["@context7/mcp-server"],
      "env": {
        "CONTEXT7_API_KEY": "your_api_key"
      }
    }
  }
}

Integration Architecture

AI Assistant
     │
     ▼
Vreko MCP Server (Local)
     │
     ├──► GitHub MCP ──► GitHub API
     ├──► Sentry MCP ──► Sentry API
     └──► Context7 MCP ──► Context7 API
          │
          ▼
    Aggregated Context
          │
          ▼
    Risk Engine (Weighted Scoring)
          │
          ▼
    Intelligence Response

Privacy Note: External MCP servers make API calls using YOUR tokens/credentials. Vreko orchestrates these calls but doesn’t store or transmit your credentials.

Backend MCP (Planned)

What’s Planned

Backend MCP will add cloud-powered capabilities to your local MCP integration:

Privacy Notice

What’s Uploaded (with Backend MCP):

• ✓ Snapshot metadata: File paths, sizes, hashes (encrypted)
• ✓ Risk analysis results: Severity scores, violation types (no code content)
• ✓ Session metadata: Session names, durations, tag data
• ✓ Policy configurations: File policies, team .vrekorc settings

What’s Never Uploaded:

• ❌ File contents (unless cloud backup is explicitly enabled)
• ❌ API keys or secrets (always redacted)
• ❌ Personal identifiable information (PII is sanitized)
• ❌ Source code snippets (only metadata and hashes)

Planned Backend Tools

cloud_backup (Planned)

Upload a snapshot to encrypted cloud storage.

Parameters:

{
  snapshotId: string;
  workspacePath: string;
  retention?: number; // days (default: tier-based)
}

cloud_restore (Planned)

Restore a snapshot from cloud storage to your local machine.

guardian_ai_score (Planned)

Analyze code using cloud-based AI risk scoring for enhanced risk detection.

Key Differences from Local analyze_risk:

• Cloud-based ML model (higher accuracy)
• Confidence scores and explanations
• 🔧 Suggested fixes for violations
• 🚀 Faster analysis for large codebases (parallel processing)

Real-Time Intelligence Channel (Planned)

What It Does

The Channel Server creates a second MCP connection that pushes Vreko intelligence alerts in real-time to your AI coding assistant, eliminating the need for manual snap_pulse checks.

Key Capabilities

Architecture

Vreko Daemon (vrekod)
         ↓ broadcasts events via IPC
Channel Server (vreko mcp --channel)
         ↓ pushes via MCP protocol
Your AI Assistant Session
         ↓ displays inline
Real-time intelligence alerts

Usage Example

Once released, you’ll enable it via .mcp.json:

{
  "mcpServers": {
    "vreko": {
      "type": "stdio",
      "command": "npx",
      "args": ["--yes", "@vreko/cli", "mcp", "--stdio", "\${workspacePath}"],
      "instructions": "Use snap_begin, snap_pulse, snap_learn, snap_end for session management."
    },
    "vreko-channel": {
      "type": "stdio",
      "command": "npx",
      "args": ["--yes", "@vreko/cli", "mcp", "--channel", "\${workspacePath}"]
    }
  }
}

Or launch Claude Code with:

claude --channels vreko-channel

Privacy & Performance

Performance Characteristics:

• ✓ Sub-50ms alert delivery from service to AI session
• ✓ Uses existing service infrastructure (no new connections)
• ✓ Workspace-scoped connection pooling prevents resource contention
• ✓ Circuit breaker pattern ensures graceful degradation

New Tool: vreko_acknowledge

The Channel Server introduces a new tool for responding to intelligence alerts:

Parameters:

{
  action: "acknowledged" | "creating_snapshot" | "proceeding_anyway";
}

Actions:

• "acknowledged" — I see the risk and will proceed carefully
• "creating_snapshot" — Creating a snapshot before proceeding (recommended for high-risk changes)
• "proceeding_anyway" — Accept the risk and continue without snapshot

Availability

Configuration for All Supported AI Assistants

Supported AI Assistants

Vreko supports 11 AI assistants with automatic MCP configuration:

1. Claude Desktop — Anthropic’s desktop app
2. Cursor — AI-first code editor
3. Windsurf — Codeium’s AI editor
4. Qoder — AI coding assistant
5. VS Code — With MCP extensions
6. Continue — Open source AI assistant
7. Cline — Claude-powered coding assistant
8. Zed — High-performance editor
9. Roo Code — AI coding companion
10. Aider — AI pair programmer (CLI)
11. Gemini/Antigravity — Google’s AI assistant

Multi-Workspace Architecture

Example:

Cursor Workspace A → vreko mcp --stdio --workspace /path/to/project-a → Process #1 ╠ local service IPC
Cursor Workspace B → vreko mcp --stdio --workspace /path/to/project-b → Process #2 ╠ local service IPC
Cursor Workspace C → vreko mcp --stdio --workspace /path/to/project-c → Process #3 ╠ local service IPC
                                                              ↓
                              ~/.vreko/service.sock (shared service, workspace-scoped sessions)

Benefits:

• ✅ Isolation — Changes in one workspace don’t affect others
• ✅ Performance — Each server only watches its own files
• ✅ Reliability — If one crashes, others keep working
• ✅ Scalability — No cross-workspace coordination overhead

Manual Configuration by Client

Understanding Transport Modes

Vreko’s MCP server can operate in different transport modes:

--stdio Mode (Recommended)

Direct local communication using standard input/output streams. This is the default and recommended mode for all local development.

vreko mcp --stdio --workspace /path/to/project

Characteristics:

• ✅ 100% local, no network requests
• ✅ Fastest response time (no network latency)
• ✅ Works completely offline
• ✅ Full privacy guarantee
• ✅ Supported by all major AI assistants

Use this when: You want local, private MCP functionality (99% of use cases).

--sse Mode (Multi-Client)

Local HTTP Server-Sent Events server for multi-client connections on localhost:8765.

# Start service with SSE transport
vreko service start

# SSE is available at http://localhost:8765/events

Characteristics:

• ✅ Multiple clients can connect simultaneously
• ✅ Persistent connections without stdin overhead
• ✅ Unified authentication with Vreko account
• ✅ Works with any SSE-compatible MCP client

Configuration:

Set the SSE port (default: 8765):

export VREKO_SSE_PORT=8765

Connecting to SSE:

Configure your MCP client to connect to the SSE endpoint:

{
  "mcpServers": {
    "vreko": {
      "url": "http://localhost:8765/events",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer sk_live_xxx"
      }
    }
  }
}

Authentication:

SSE transport supports two authentication methods:

1. API Key (recommended): Use your Vreko API key (sk_live_xxx or sk_test_xxx)

   • Validated against api.vreko.dev
   • Provides user context (tier, permissions) for rate limiting

2. Local Token: Automatically uses your CLI login session

   • Retrieved from ~/.vreko/mcp-token
   • No additional configuration needed

Use this when: Running multiple AI assistants simultaneously or need persistent connections.

shim Mode (Advanced)

A stdio-to-SSE bridge that proxies local stdio requests to a remote Server-Sent Events endpoint at https://vreko-mcp.fly.dev.

vreko mcp shim --workspace /path/to/project

Characteristics:

• Connects to remote Fly.io server
• 🌐 Requires internet connectivity
• ⚠️ May encounter 404 errors if server not deployed
• 🔄 Intended for stdio-only clients that need remote features

Use this when: You specifically need to connect stdio-only clients (like certain AI assistants) to a remote SSE-enabled MCP server.

"args": ["mcp", "shim", "--workspace", "..."]

"args": ["mcp", "--stdio", "--workspace", "..."]

1. Claude Desktop

Config File Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Manual Configuration:

{
  "mcpServers": {
    "vreko": {
      "command": "npx",
      "args": [
        "@vreko/cli",
        "mcp",
        "--stdio",
        "--workspace",
        "/path/to/your/project"
      ]
    }
  }
}

2. Cursor

Config File Locations (for manual setup):

• Project-level: .cursor/mcp.json in your project root
• Global: ~/.cursor/mcp.json

Manual Configuration:

{
  "mcpServers": {
    "vreko": {
      "command": "npx",
      "args": [
        "@vreko/cli",
        "mcp",
        "--stdio",
        "--workspace",
        "\${workspaceFolder}"
      ]
    }
  }
}

3. Windsurf

Config File Location (for manual setup): ~/.codeium/windsurf/mcp_config.json

Manual Configuration:

{
  "mcpServers": {
    "vreko": {
      "command": "npx",
      "args": [
        "@vreko/cli",
        "mcp",
        "--stdio",
        "--workspace",
        "\${workspaceFolder}"
      ]
    }
  }
}

4. Qoder

Config File Locations:

• macOS: ~/Library/Application Support/Qoder/SharedClientCache/extension/local/mcp.json
• Windows: %APPDATA%\Qoder\mcp.json
• Linux: ~/.config/Qoder/mcp.json
• Project-level: .qoder-mcp-config.json in your project root

Configuration:

{
  "mcpServers": {
    "vreko": {
      "command": "npx",
      "args": [
        "@vreko/cli",
        "mcp",
        "--stdio",
        "--workspace",
        "\${workspaceFolder}"
      ]
    }
  }
}

5. VS Code

Config File Location: .vscode/mcp.json in your project root

Configuration:

{
  "servers": {
    "vreko": {
      "command": "npx",
      "args": [
        "@vreko/cli",
        "mcp",
        "--stdio",
        "--workspace",
        "\${workspaceFolder}"
      ]
    }
  }
}

6. Continue

Config File Location: ~/.continue/config.json

Configuration:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "name": "vreko",
        "command": "npx",
        "args": [
          "@vreko/cli",
          "mcp",
          "--stdio"
        ]
      }
    ]
  }
}

7. Cline

Config File Location: ~/.cline/mcp.json

Configuration:

{
  "mcpServers": {
    "vreko": {
      "command": "npx",
      "args": [
        "@vreko/cli",
        "mcp",
        "--stdio",
        "--workspace",
        "\${workspaceFolder}"
      ]
    }
  }
}

8. Zed

Config File Location: ~/.config/zed/settings.json

Configuration:

{
  "context_servers": {
    "vreko": {
      "command": "npx",
      "args": [
        "@vreko/cli",
        "mcp",
        "--stdio"
      ]
    }
  }
}

9. Roo Code

Config File Location: ~/.roo-code/mcp.json

Configuration:

{
  "mcpServers": {
    "vreko": {
      "command": "npx",
      "args": [
        "@vreko/cli",
        "mcp",
        "--stdio",
        "--workspace",
        "\${workspaceFolder}"
      ]
    }
  }
}

10. Aider (CLI)

Config File Location: ~/.aider/mcp.yaml

Configuration (YAML):

servers:
  vreko:
    command: npx
    args:
      - "@vreko/cli"
      - mcp
      - --stdio

11. Gemini/Antigravity

Config File Location: ~/.gemini/settings.json

Configuration:

{
  "context_servers": {
    "vreko": {
      "command": "npx",
      "args": [
        "@vreko/cli",
        "mcp",
        "--stdio"
      ]
    }
  }
}

Troubleshooting MCP Connections

Status Bar Indicators

The Vreko VS Code extension shows status in the status bar using the 🦎 prefix. Setup gates appear first if any precondition is unmet:

Common Issue: Status Bar Still Shows a Gate State

Symptom: You resolved a setup step (e.g. installed the CLI, configured MCP) but the status bar still shows the gate message.

Why this happens: The status bar refreshes when Vreko detects a relevant change, such as a service state transition. If the service was already running and stable, no event fires immediately after you complete a step.

Fix: Click the status bar item again — it re-evaluates all gates. If that doesn’t work, reload VS Code (⌘+Shift+P → Developer: Reload Window).

Common Issue: MCP Tools Work but Service Shows Disconnected

Symptom: Your AI assistant can call vreko tools, but the status bar shows $(sync~spin) Starting Vreko... or the service appears offline.

What’s happening: The MCP server process is running independently of the service socket connection. MCP tool calls can still succeed if the server process is alive, even when the service socket is temporarily broken.

Solution:

1. Run ⌘+Shift+P → Vreko: MCP Reconnect to force a fresh service connection.
2. If reconnection fails, run ⌘+Shift+P → Vreko: MCP Diagnose to see actual state.
3. As a last resort, run ⌘+Shift+P → Vreko: MCP Reset, then reload VS Code.

Checking MCP Process Status

See all running MCP servers:

# Check running Vreko MCP processes
ps aux | grep "vreko mcp"

Expected output for 3 workspaces:

user  12345  node /path/to/cli/dist/index.js mcp --stdio --workspace /Users/you/project-a
user  12346  node /path/to/cli/dist/index.js mcp --stdio --workspace /Users/you/project-b
user  12347  node /path/to/cli/dist/index.js mcp --stdio --workspace /Users/you/project-c

Check service socket:

ls -la ~/.vreko/service.sock

If the socket doesn’t exist, the service isn’t running. Start it with:

vreko service start --no-detach

Multi-Workspace Troubleshooting

Problem: One workspace’s MCP works, others don’t.

Cause: Each workspace has its own MCP server process with a different workspace path.

Solution:

1. Verify each workspace has correct path:

   # Check running processes
   ps aux | grep "vreko mcp"
   
   # Look for --workspace arguments
   # Each should point to its respective project root

2. Check project-level configs:

   # In each project
   cat .cursor/mcp.json
   cat .qoder-mcp-config.json
   cat .vscode/mcp.json

3. Ensure the workspaceFolder variable is used:

   • Good: --workspace with workspaceFolder
   • Bad: Hardcoded path like /path/to/project

Session Not Linking (snap_begin / snap_end)

Symptom: snap_begin returns a session briefing, but snap_end responds with “No active session to close” or diagnostics showing workspace: default.

Root cause: The MCP server is not connecting to your local service. Session state lives in the local service (~/.vreko/service.sock) and requires the MCP server to run locally on your machine.

Diagnostic checklist:

1. Confirm the service socket exists:

   ls -la ~/.vreko/service.sock
   vreko service status

   If missing: vreko service start --no-detach

2. Check the workspace shown in diagnostics: When snap_end fails it prints a workspace: field. If it shows default instead of your actual project path, the MCP server received no workspace parameter.

   Fix: ensure your MCP config passes the workspace path:

   "args": ["mcp", "--stdio", "--workspace", "\${workspaceFolder}"]

3. Confirm the MCP binary runs locally: The Vreko MCP server must run as a local process on your machine — not as a remote proxy.

   Verify which process is serving your AI assistant:

   # Check running vreko processes
   ps aux | grep vreko

   You should see a local vreko mcp process, not a network connection to a remote host.

4. Rebuild the MCP server bundle (if the binary is stale):

   pnpm --filter @vreko/cli build

   Then reload your AI assistant.

5. Reset and reconnect:

   ⌘+Shift+P → Vreko: MCP Reset
   ⌘+Shift+P → Vreko: MCP Reconnect

CLI Not Installed

Symptom: Status bar shows $(warning) Install Vreko CLI.

Solution:

1. Install Vreko CLI globally:

   npm install -g @vreko/cli

2. Verify installation:

   vreko --version
   npx @vreko/cli --version

3. Restart your AI assistant (Cursor, Qoder, etc.)

Configuration Priority

Vreko looks for MCP configuration in this order:

1. Project-level config (highest priority)

   • .cursor/mcp.json
   • .qoder-mcp-config.json
   • .vscode/mcp.json
   • .windsurf/mcp.json

2. Global config

   • ~/.cursor/mcp.json
   • ~/Library/Application Support/Qoder/.../mcp.json
   • etc.

Auto-Configuration

How it works:

1. Install Vreko VS Code extension
2. Extension auto-detects installed AI assistants
3. Silently configures MCP for each one
4. Shows toast confirming protection is active

No manual configuration needed!

Supported for auto-configuration:

• ✅ Claude Desktop
• ✅ Cursor
• ✅ Windsurf
• ✅ Qoder
• ✅ VS Code
• ✅ Continue
• ✅ Cline
• ✅ Zed
• ✅ Roo Code

Manual configuration needed:

• ⚠️ Aider (CLI tool, no auto-detect)
• ⚠️ Gemini (less common, may need manual setup)

To manually trigger auto-configuration:

Command Palette → Vreko: Configure MCP

Validation Commands

Check your MCP configuration:

# Scan for all AI assistants
vreko mcp scan

# Validate configurations
vreko mcp validate

# Repair broken configurations
vreko mcp repair

VS Code setup commands (status bar gate actions):

Vreko: Install CLI          — Install the Vreko CLI
Vreko: Start Service        — Start the background service
Vreko: Sign In              — Authenticate with Vreko
Vreko: Initialize Workspace — Initialize this workspace
Vreko: Configure MCP        — Auto-configure MCP for your AI tools

VS Code MCP commands:

Vreko: MCP Diagnose     — Show connection status
Vreko: MCP Reconnect    — Force reconnection
Vreko: MCP Reset        — Reset configuration state
Vreko: MCP Validate     — Check all configurations
Vreko: MCP Status       — Quick status check

Next Steps

• Install Vreko — Get started in 2 minutes
• CLI Reference — Use Vreko from the terminal
• How It Works — How Vreko detects AI changes
• Troubleshooting — Common issues and fixes