GitHub - vreko-dev/mcp-server: Vreko MCP server — codebase intelligence via Model Context Protocol.

Vreko

AI-powered context server for the Vreko platform.
Enables Claude, Cursor, and other AI assistants to coordinate with your code intelligence system.

Quick Start · About · Architecture · API · Documentation

What is Vreko MCP Server?

Vreko MCP Server is a Model Context Protocol (MCP) server that gives AI coding agents a session memory and intelligence layer. It enables Claude, Cursor, Windsurf, and any MCP-compatible assistant to:

Brief themselves before every task - past learnings, active warnings, risk context
Check vitals mid-session - activity level, risk pressure, trajectory
Capture discoveries - patterns, gotchas, and decisions that carry forward to future sessions
Close with ceremony - session outcome recorded, compound intelligence grows

Key Capabilities:

Feature	Description
Session Intelligence	`vreko` → `vreko_pulse` → `vreko_learn` → `vreko_end` - the agentic coding loop
Pattern Memory	Learns your codebase’s specific failure modes over time
Multi-Assistant Support	Works with Claude, Cursor, Windsurf, and any MCP-compatible client
Cloud & Local Modes	Deploy to Fly.io or run locally via CLI
Security-First	API key validation, path traversal protection, CORS security

Quick Start

1. Install

Option A: npx (No Installation)

npx vreko-mcp-server

Option B: Global Install

npm install -g vreko-mcp-server
vreko-mcp-server

Option C: Docker

docker run -p 8080:8080 -e VREKO_API_KEY=your_key vreko/mcp-server

2. Configure Your AI Assistant

Claude Desktop Config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "vreko": {
      "command": "npx",
      "args": ["vreko-mcp-server"],
      "env": {
        "VREKO_API_KEY": "YOUR_VREKO_API_KEY"
      }
    }
  }
}

Cursor Config (Settings → MCP):

{
  "mcpServers": {
    "vreko": {
      "command": "npx",
      "args": ["vreko-mcp-server"],
      "env": {
        "VREKO_API_KEY": "YOUR_VREKO_API_KEY"
      }
    }
  }
}

3. Verify Installation

# Health check
curl http://localhost:8080/health

# Expected response:
{"status":"healthy","version":"1.0.0","timestamp":"2026-01-..."}

Architecture

Wraps the CLI-based MCP server (packages/mcp) in an Express HTTP server that can be deployed to Fly.io or other cloud providers. This allows Claude Desktop, Cursor, and other AI tools to connect to Vreko over HTTPS instead of requiring local installation.

┌─────────────────────────────────────────────────────────────┐
│                    AI Assistant Clients                      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │Claude Desktop│  │    Cursor    │  │  Other MCP Tools │  │
│  └──────┬───────┘  └──────┬───────┘  └────────┬─────────┘  │
└─────────┼─────────────────┼───────────────────┼────────────┘
          │                 │                   │
          └─────────────────┼───────────────────┘
                            ▼ HTTPS
┌─────────────────────────────────────────────────────────────┐
│                    apps/mcp-server                           │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  Express HTTP Server  •  API Key Auth  •  CORS         │ │
│  │  • Request Validation  •  Error Handling  •  Logging   │ │
│  └────────────────────┬───────────────────────────────────┘ │
└───────────────────────┼─────────────────────────────────────┘
                        ▼ Stdio
┌─────────────────────────────────────────────────────────────┐
│                    packages/mcp                              │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  MCP Protocol Handler  •  Tool Registry  •  Context    │ │
│  └────────────────────┬───────────────────────────────────┘ │
└───────────────────────┼─────────────────────────────────────┘
                        ▼
┌─────────────────────────────────────────────────────────────┐
│                    Vreko Platform                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │Pattern Memory│  │  Snapshot    │  │   Intelligence   │  │
│  │   Engine     │  │   Engine     │  │     Layer        │  │
│  └──────────────┘  └──────────────┘  └──────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Component Responsibilities

Component	Responsibility
HTTP Server	Handles HTTPS requests, authentication, request/response formatting
MCP Protocol	Implements Model Context Protocol spec, tool registration, JSON-RPC
Vreko Core	Pattern analysis, snapshot management, learning capture

Local Development

Build

pnpm build

Run

# Development
PORT=8080 NODE_ENV=development node dist/index.js

# With API key
VREKO_API_KEY=YOUR_VREKO_API_KEY PORT=8080 node dist/index.js

Test Health

curl http://localhost:8080/health

Test MCP Call

# Initialize MCP session (standard JSON-RPC initialize handshake)
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "x-workspace-path: /path/to/your/project" \
  -H "x-api-key: YOUR_VREKO_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

Deployment to Fly.io

Quick Deploy (Recommended)

From the monorepo root:

# Full deployment with pre-flight checks and verification
pnpm --filter=vreko-mcp-server deploy

# Dry run (validates without deploying)
pnpm --filter=vreko-mcp-server deploy:dry-run

The deploy script automatically:

✅ Validates Fly CLI is installed and authenticated
✅ Checks for uncommitted changes
✅ Builds and validates the bundle
✅ Deploys to Fly.io
✅ Verifies health and /bridge/push endpoints after deployment

Alternative Deploy Methods

# Quick deploy (skips pre-flight checks)
pnpm --filter=vreko-mcp-server deploy:quick

# Force immediate deployment (no rolling update)
pnpm --filter=vreko-mcp-server deploy:force

# Check deployment status
pnpm --filter=vreko-mcp-server deploy:status

# View live logs
pnpm --filter=vreko-mcp-server deploy:logs

# View releases for rollback
pnpm --filter=vreko-mcp-server deploy:rollback

First-Time Setup

If deploying for the first time:

# 1. Login to Fly.io
fly auth login

# 2. Create the app (only once)
fly apps create vreko-mcp

# 3. Set secrets
fly secrets set VREKO_API_KEY=YOUR_VREKO_API_KEY -a vreko-mcp
fly secrets set CORS_ORIGIN=https://your-domain.com -a vreko-mcp

# 4. Deploy
pnpm --filter=vreko-mcp-server deploy

CI/CD Deployment

Automatic deployments are triggered on push to main when changes are detected in:

apps/mcp-server/**
packages/mcp/**, packages/core/**, packages/intelligence/**

Required GitHub Secret: FLY_API_TOKEN

Generate a token: fly tokens create deploy -x 999999h

Verify Deployment

# Health check
curl https://vreko-mcp.fly.dev/health

# Bridge endpoint test
curl -X POST https://vreko-mcp.fly.dev/bridge/push \
  -H "Content-Type: application/json" \
  -d '{"workspaceId":"ws_00000000000000000000000000000000","observations":[]}'

Expected responses:

{"status":"healthy","uptime":123.456,"timestamp":"2025-01-06T...","version":"1.0.0"}
{"received":true,"observationsCount":0,"changesCount":0}

Rollback

If something goes wrong:

# List recent releases
fly releases -a vreko-mcp

# Rollback to a previous version
fly releases rollback v123 -a vreko-mcp

Configuration

Environment Variables

Variable	Default	Description
`PORT`	8080	Server port
`NODE_ENV`	development	Environment (production/development)
`VREKO_API_KEY`	(required)	API key for authentication
`CORS_ORIGIN`	*	Allowed CORS origins (comma-separated)
`LOG_LEVEL`	info	Logging level

Fly.io Secrets

Set via fly secrets set KEY=value:

fly secrets set VREKO_API_KEY=YOUR_VREKO_API_KEY
fly secrets set CORS_ORIGIN=https://your-app.com

View secrets:

fly secrets list

The V2 Agentic Workflow

Vreko MCP exposes a 4-tool session API designed for the agentic coding loop. Configure once, and your AI assistant uses it automatically:

Tool	When	What it does
`vreko`	Task start	Returns intelligence briefing: recent learnings, active warnings, session lineage
`vreko_pulse`	Mid-session	Read-only vitals: pulse level, risk pressure, trajectory
`vreko_learn`	Any discovery	Records a pattern, gotcha, or decision for future sessions
`vreko_end`	Task complete	Closes session with ceremony - outcome, carry-forward context

vreko({ task: "add rate limiting to API" })
  → briefing: 3 past learnings, 1 active warning, lineage from last session

  [... agent works ...]

vreko_pulse()
  → pulse: racing, pressure: 71%, trajectory: increasing  -  snapshot recommended

vreko_learn({ insight: "rate limiting config is shared  -  test in staging first" })

vreko_end({ outcome: "completed" })
  → ceremony: 4 files modified, 1 learning captured, context carried forward

The full consolidated surface is also available: check, advise, guide, safe_to_write, intelligence and refactoring tools. See MCP documentation →

API Reference

`GET /health`

Health check endpoint.

Response:

{
  "status": "healthy",
  "uptime": 123.456,
  "timestamp": "2024-12-30T...",
  "version": "1.0.0"
}

`POST /mcp`

Main MCP endpoint - handles standard JSON-RPC 2.0 requests per the MCP protocol spec.

Headers:

x-workspace-path: /absolute/path/to/project
x-api-key: YOUR_VREKO_API_KEY
mcp-session-id: (returned from initialize, required for subsequent calls)

Example - initialize session:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0"}}}

Response: Standard JSON-RPC 2.0 response. The mcp-session-id header in the response must be included in all subsequent requests.

Security

Authentication: Required apiKey parameter (validated against VREKO_API_KEY)
HTTPS Only: Fly.io auto-configures HTTPS on port 443
CORS: Configurable via CORS_ORIGIN environment variable
Non-root user: Container runs as unprivileged user
Request timeouts: 30-second timeout on MCP calls
Rate limiting: Consider adding in production (not yet implemented)

Monitoring

Logs

fly logs

Metrics

# CPU/Memory usage
fly scale show

# App status
fly status

Scaling

Edit fly.toml:

[scaling]
min_count = 1
max_count = 5

Then deploy:

fly deploy

Troubleshooting

"Connection refused"

Ensure Fly.io app is running:

fly status

"Unauthorized"

Check that API key is set:

fly secrets list

Should show VREKO_API_KEY.

"MCP server timeout"

Default timeout is 30 seconds. Check workspace size and API key validity.

Logs show errors

View detailed logs:

fly logs --follow

Integration with VS Code Extension

Quick Setup (2 steps)

Get your API key from deployment output (look for YOUR_VREKO_API_KEY)
Configure VS Code settings:

{
  "vreko.mcp.enabled": true,
  "vreko.mcp.serverUrl": "https://vreko-mcp.fly.dev",
  "vreko.mcp.authType": "apikey"
}

Store your API key securely using VS Code command palette:
- Press Cmd+Shift+P / Ctrl+Shift+P
- Run: Vreko: Set MCP Auth Token (Secure)
- Paste your API key: YOUR_VREKO_API_KEY

Configuration Options

Setting	Default	Description
`vreko.mcp.enabled`	`true`	Enable MCP integration
`vreko.mcp.serverUrl`	`https://mcp.vreko.dev`	Remote MCP server URL
`vreko.mcp.authType`	`bearer`	Authentication type (`bearer` or `apikey`)
`vreko.mcp.timeout`	`5000`	Request timeout in milliseconds

Programmatic Usage

The VS Code extension automatically uses RemoteMCPClient when serverUrl is configured:

const client = new RemoteMCPClient({
  serverUrl: 'https://vreko-mcp.fly.dev',
  apiKey: 'YOUR_VREKO_API_KEY',
  authType: 'apikey',
  timeout: 5000,
  maxRetries: 3,
});

await client.connect();

See apps/vscode/src/services/RemoteMCPClient.ts for implementation details.

Health Check

Verify the server is accessible:

curl https://vreko-mcp.fly.dev/health

Expected response:

{"status":"healthy","uptime":123.45,"timestamp":"2025-12-31T...","version":"1.0.0"}

Cost

Fly.io free tier includes:

3 shared-cpu-1x VMs (256MB each)
160GB bandwidth/month

This MCP server easily fits within free tier for individual/small team use.

Status

Metric	Value
Version	3.1.0
License	Apache-2.0
Status	Production Ready
Node.js	>= 20.0.0

References

_{Built with 💚 by Marcelle Labs}

Website • Docs • Discord • Issues

Name		Name	Last commit message	Last commit date
Latest commit History 827 Commits
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
banner.png		banner.png
github-mcp.png		github-mcp.png
lockup-dark.png		lockup-dark.png
lockup-white.png		lockup-white.png
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

What is Vreko MCP Server?

Quick Start

1. Install

2. Configure Your AI Assistant

3. Verify Installation

Architecture

Component Responsibilities

Local Development

Build

Run

Test Health

Test MCP Call

Deployment to Fly.io

Quick Deploy (Recommended)

Alternative Deploy Methods

First-Time Setup

CI/CD Deployment

Verify Deployment

Rollback

Configuration

Environment Variables

Fly.io Secrets

The V2 Agentic Workflow

API Reference

GET /health

POST /mcp

Security

Monitoring

Logs

Metrics

Scaling

Troubleshooting

"Connection refused"

"Unauthorized"

"MCP server timeout"

Logs show errors

Integration with VS Code Extension

Quick Setup (2 steps)

Configuration Options

Programmatic Usage

Health Check

Cost

Status

References

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

`GET /health`

`POST /mcp`

Packages