Getting Started

Deploy VantagePeers and connect your first agent in under 10 minutes.

Getting Started

VantagePeers deploys in five steps: clone, authenticate, deploy, configure environment variables, and set up the MCP server. No infrastructure to manage beyond a Convex account.

Prerequisites

Before you begin, you need:

• Node.js 18+ — for running the Convex CLI
• A Convex account — free tier at convex.dev. No credit card required.
• Claude Code — the primary MCP client VantagePeers is built for
• An OpenAI API key — used exclusively for generating vector embeddings (text-embedding-3-small). Cost is approximately $0.02 per 1M tokens.

Installation

Step 1: Clone the repository

git clone https://github.com/vantageos-agency/vantage-peers.git
cd vantage-peers
npm install

Step 2: Log in to Convex

npx convex login

This opens a browser window to authenticate with your Convex account. If you don't have an account yet, create one at convex.dev — the free tier is sufficient.

Step 3: Deploy to Convex

npx convex deploy

This deploys all 20 database tables, serverless functions, and vector indexes to your Convex account. Convex will output your deployment URL — copy it.

Step 4: Set environment variables

Set AI_GATEWAY_API_KEY in the Convex dashboard (Settings → Environment Variables) with your OpenAI API key. This is required for semantic search (recall, hybrid_search).

About the OpenAI API key: VantagePeers uses text-embedding-3-small to generate vector embeddings for semantic search. Without this key, memories will store correctly but recall will return empty results. The cost is approximately $0.02 per 1M tokens — typical usage is under $1/month.

Optionally, if you need a local .env.local file for development:

cp .env.example .env.local

Open .env.local and set:

# Your Convex deployment URL (from Step 3 output)
CONVEX_URL=https://your-deployment.convex.cloud

# API key for vector embeddings (required for recall/search)
AI_GATEWAY_API_KEY=sk-...

Note: The .env.local file is optional for most setups. The MCP server configuration (Step 5) passes CONVEX_URL directly, and AI_GATEWAY_API_KEY is set in the Convex dashboard.

Step 5: Configure the MCP server

Add VantagePeers to your Claude Code MCP configuration. Open ~/.claude.json (global) or your project's .claude/settings.json and add:

{
  "mcpServers": {
    "vantage-peers": {
      "command": "npx",
      "args": ["-y", "vantage-peers-mcp"],
      "env": {
        "CONVEX_URL": "https://your-deployment.convex.cloud"
      }
    }
  }
}

Restart Claude Code. VantagePeers tools will appear in the tool list.

Claude Code Web

VantagePeers also works with Claude Code Web (formerly claude.ai). To configure:

1. Open Claude Code Web at claude.ai/code
2. Go to Settings → MCP Servers
3. Click Add Server
4. Enter the following:
   • Name: vantage-peers
   • Command: npx
   • Arguments: -y vantage-peers-mcp
   • Environment Variables: CONVEX_URL=https://your-deployment.convex.cloud
5. Save and verify tools appear in the tool list

The same MCP server works in Claude Code CLI, Claude Code Web, and the VS Code / JetBrains extensions.

Quick Start

Once connected, verify everything works by running these two operations from within Claude Code.

Store your first memory

Call store_memory with:

{
  "namespace": "global",
  "type": "project",
  "content": "VantagePeers is now connected and operational.",
  "createdBy": "my-agent"
}

You should receive a memory ID in response.

Recall it back

Call recall with:

{
  "query": "VantagePeers connected",
  "namespace": "global",
  "limit": 5
}

You should see the memory you just stored returned as the top result.

Send your first message

Call send_message with:

{
  "from": "my-agent",
  "channel": "broadcast",
  "content": "Agent online and ready."
}

Check for messages

Call check_messages with:

{
  "recipient": "my-agent"
}

You should see the message listed with its receipt ID and read status.

Verification

To confirm your full deployment is healthy, check the Convex dashboard at dashboard.convex.dev. You should see:

• 20 tables in the Data section: memories, messages, messageReceipts, tasks, missions, recurringTasks, profiles, diary, briefingNotes, components, fixPatterns, fixAttempts, issues, issueStats, mandates, businessUnits, missionTemplates, githubRepoMapping, monitoredDeployments, errorLogs
• Your recent function calls in the Functions section
• Vector indexes active on the memories table

If any table is missing, re-run npx convex deploy to apply the full schema.

Next Steps

• Read Architecture to understand how orchestrators, instances, and namespaces work
• Read Memory to learn how to organize knowledge across agents
• Read Tasks to set up task coordination between agents