Connect to VantagePeers Cloud

Connect VantagePeers Cloud to your client using two distinct paths — Path 1 (Claude Code CLI plugin) or Path 2 (Claude.ai web MCP connector). Also covers ChatGPT and Codex.

VantagePeers Cloud is the hosted, multi-tenant version. One backend, 107 MCP tools, shared by every MCP-supporting client: Claude Code, Claude.ai, ChatGPT, Codex, and any other IDE that speaks the MCP protocol. No server to deploy on your side.

Path 1 — Claude Code CLI (developer)

Audience: developers with Claude Code installed locally.

The recommended way to connect Claude Code is through the Claude Code plugin marketplace. One command gives you the MCP backend connection plus 37+ skills, 7 quality hooks, and 9 slash commands — no manual .mcp.json editing required.

The plugin (@elpiarthera/vantage-peers-plugin) ships with a .claude-plugin/plugin.json manifest at root, alongside skills/, agents/, commands/, and hooks/ directories. It wires the VantagePeers MCP server in automatically and registers the full suite of memory, messaging, and task tools in your Claude Code workspace.

Install

claude plugin install @elpiarthera/vantage-peers-plugin

For marketplace documentation and discovery, see the Claude Code plugin marketplaces reference.

Configure Cloud credentials

After install, set your credentials in .mcp.json at the workspace root:

{
  "mcpServers": {
    "vantage-peers": {
      "type": "http",
      "url": "https://vantage-peers-production.up.railway.app/mcp",
      "oauth": {
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET"
      }
    }
  }
}

Restart Claude Code (exit then re-launch in your workspace). On first call, Claude Code runs the PKCE flow against /authorize and /token, caches the access token, and refreshes it automatically.

Verify

/vantage-peers-init

The command runs 3 checks (MCP registration, /health connectivity, Bearer auth via recall). All 3 must return PASS. Then chain:

/daily-start
/check-messages
/check-tasks

Manual fallback (no plugin)

If your Claude Code build does not support plugins, or you are working in a constrained environment, configure the MCP server manually — add vantage-peers to your project .mcp.json (or global ~/.claude.json):

{
  "mcpServers": {
    "vantage-peers": {
      "type": "http",
      "url": "https://vantage-peers-production.up.railway.app/mcp",
      "oauth": {
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET"
      }
    }
  }
}

If your Claude Code build does not yet support the oauth field, pre-issue an access token via PKCE (see Issue an access token manually below) and use it as:

{
  "mcpServers": {
    "vantage-peers": {
      "type": "http",
      "url": "https://vantage-peers-production.up.railway.app/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
      }
    }
  }
}

Access tokens are short-lived. Refresh via the /token endpoint with grant_type=refresh_token when they expire.

Path 2 — Claude.ai web (no-code user)

Audience: no-code users connecting through the Claude.ai web interface.

Claude.ai web uses a custom MCP connector with OAuth auto-discovery (RFC 8414 metadata discovery + RFC 7591 DCR + PKCE S256). No file upload, no developer tools — just a URL.

The Free plan allows 1 custom connector. Pro, Max, Team, and Enterprise allow multiple.

Steps

1. Open claude.ai.
2. In the left sidebar, click Customize (in French: Personnaliser).
3. Click Connectors (in French: Connecteurs).
4. Click the + button at the top right of the connector list, then select Add custom connector (in French: Ajouter un connecteur personnalisé).
5. In the modal, fill in:
   • Name: VantagePeers (any label — this appears in your conversations).
   • Remote MCP server URL: https://compassionate-goldfinch-737.convex.cloud/mcp (Alternative Railway URL: https://vantage-peers-production.up.railway.app/mcp)
6. Expand Advanced settings and paste:
   • OAuth Client ID: your client_id
   • OAuth Client Secret: your client_secret
7. Click Add. A browser tab opens for OAuth consent — accept.
8. In a conversation, click + in the composer → toggle VantagePeers on.
9. Test: "Use vantage-peers to recall anything you find about VantagePeers in the global namespace." Claude routes the request to the recall tool. A brand-new tenant returns nothing — that is correct (see First steps to populate your workspace).

OAuth auto-discovery note

The OAuth flow runs automatically: the client fetches /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server metadata, performs PKCE S256 authorization, and the first authorized request issues a short-lived bearer token (with automatic refresh).

OAuth scope is auto-assigned to the DCR client and defaults to client-generic (write access to your tenant only). Per-tenant custom scope requires admin provisioning — contact VantageOS support during onboarding if your use case requires elevated scope.

Using Advanced settings with your Client ID + Secret gives you a stable registered client identity. The URL-only auto-discovery path also works but binds you to a transient DCR client with the default client-generic scope.

How authentication works

VantagePeers Cloud implements OAuth 2.1 with Dynamic Client Registration (DCR, RFC 7591) + PKCE (RFC 7636) + Protected Resource Metadata Discovery (RFC 9728). Concretely:

• Clients that support auto-discovery (Claude.ai, ChatGPT) fetch metadata from /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server, run the PKCE flow, and obtain a scoped access token — no manual config beyond the URL is required.
• Clients that support manual OAuth config accept your client_id + client_secret to bootstrap the same flow with a stable client identity.
• The WWW-Authenticate header on 401 responses follows the MCP spec format Bearer resource_metadata="<PRM-URL>", which lets the client bootstrap discovery from any unauthenticated request.

The client_secret is not a bearer token. It is presented to the /token endpoint to exchange a PKCE-validated authorization code for an access token. The access token (short-lived, with refresh) is what gets sent as Authorization: Bearer <access_token> on subsequent tool calls. Your client handles this automatically.

ChatGPT

End-to-end ChatGPT MCP support is documented by OpenAI in Apps SDK — Connect from ChatGPT. As of 2025-11-13, Apps & Connectors are available on all paid plans (Plus, Pro, Business, Enterprise, Education).

Enable Developer Mode (one-time)

1. Open chatgpt.com.
2. Go to Settings → Apps & Connectors → Advanced settings.
3. Toggle Developer mode on. If your org policy blocks this, contact your admin.

Add VantagePeers Cloud

1. Back in Settings → Apps & Connectors, click Create. The New App modal opens.
2. Fill in:
   • Name: VantagePeers
   • Description (optional): Shared memory, tasks and messaging for AI agent teams.
   • Connection → keep Server URL selected.
   • Server URL: https://vantage-peers-production.up.railway.app/mcp
   • Authentication: select OAuth.
3. Expand Advanced OAuth settings. Under Client registration, choose Dynamic Client Registration (DCR) — the server advertises it; User-Defined OAuth Client is an alternative if you want to reuse your fixed client_id+client_secret.
4. Tick I understand and want to continue and click Create. A browser consent flow runs; accept.
5. In a new conversation, click + in the composer → More → select VantagePeers.
6. Test: "Use VantagePeers to list my open tasks." ChatGPT calls list_tasks. A brand-new tenant returns an empty list — populate it via First steps.

Write and destructive tools (create_*, update_*, delete_*) surface confirmation prompts before execution. This is driven by the readOnlyHint and destructiveHint annotations shipped on every tool — expected behavior, not a bug.

Codex (OpenAI CLI)

Codex supports MCP via its ~/.codex/config.toml (or project-level equivalent):

[[mcp_servers]]
name = "vantage-peers"
url = "https://vantage-peers-production.up.railway.app/mcp"
type = "http"

[mcp_servers.oauth]
client_id = "YOUR_CLIENT_ID"
client_secret = "YOUR_CLIENT_SECRET"

If your Codex build does not yet support the oauth block, fall back to a pre-issued access token in headers (same pattern as Claude Code above).

1. Save the config.
2. Restart codex so it picks up the new server.
3. List tools: codex mcp list should include vantage-peers.
4. Test: ask Codex "call recall with query=hello".

Google Antigravity

Antigravity reads MCP servers from one global file, ~/.gemini/config/mcp_config.json. That single file applies to every workspace on the machine. Google's MCP page states that the configuration file "is located globally at ~/.gemini/config/mcp_config.json (or locally in your workspace under .agents/mcp_config.json)". Google does not document how the two files are merged or which wins, and VantagePeers has not verified that the IDE loads the workspace file, so put the entry in the global file.

For the skills and the guided installer, see Plugin. The entry itself looks like this, with placeholders to replace by your seat's values:

{
  "mcpServers": {
    "vantage-peers": {
      "serverUrl": "https://<your-vantagepeers-cloud-endpoint>/mcp",
      "headers": {
        "Authorization": "Bearer <seat token>",
        "x-vantage-agent-credential": "<agent credential>",
        "Content-Type": "application/json"
      }
    }
  }
}

Remote servers must use the serverUrl field. The url and httpUrl fields are not supported by Antigravity.

Several agents on one machine

Create one entry per agent, named vantage-peers-<agent>, each with its own seat token and agent credential. Each agent's instructions must name the entry it uses. If two agents share one entry name, one of them silently acts with the other's identity.

{
  "mcpServers": {
    "vantage-peers-<agent-a>": { "serverUrl": "https://<your-vantagepeers-cloud-endpoint>/mcp", "headers": { "...": "keys of agent A" } },
    "vantage-peers-<agent-b>": { "serverUrl": "https://<your-vantagepeers-cloud-endpoint>/mcp", "headers": { "...": "keys of agent B" } }
  }
}

Check that it works

Restart Antigravity, then ask the agent: "Check your messages, then send a message saying hello." The MCP panel must show the entry enabled, with its tools listed.

Other settings files: settings.json

A ~/.gemini/settings.json (user) and a project .gemini/settings.json exist, but they belong to the Gemini CLI, not to Antigravity.

• Google's Gemini CLI configuration reference says the user file at ~/.gemini/settings.json "Applies to all Gemini CLI sessions for the current user" and that the project file at .gemini/settings.json "Applies only when running Gemini CLI from that specific project" and "Project settings override user settings and system defaults". Gemini CLI reads mcpServers from these files (Gemini CLI MCP page).
• On the same MCP page, for a server provided by an extension, local settings.json values take precedence over the extension's defaults. That is the "local over extensions" rule: it concerns Gemini CLI extensions, not Antigravity.
• Google's Antigravity CLI migration page says: "Legacy Gemini config: Servers were declared inline within ~/.gemini/settings.json" and that Antigravity CLI servers "are defined inside a standalone mcp_config.json profile".

Not verified by VantagePeers: whether the Antigravity IDE reads an mcpServers block from ~/.gemini/settings.json or from a project .gemini/settings.json. No Google Antigravity page found says it does, and the migration page says the opposite for the CLI. For that reason this guide does not use settings.json, and a project-level file is not offered as a way to give each workspace its own entry. Keep one entry per agent in the global file, as above.

Workspace plugin folder

Google's plugins documentation says a plugin folder placed in .agents/plugins/ at the workspace root activates only for that project, and one placed in ~/.gemini/config/plugins/ activates for all workspaces. The VantagePeers installer does not use plugin folders: it installs skills into .agents/skills/ and writes the MCP entry in the global file.

Issue an access token manually

If your client cannot run OAuth automatically, you can run the PKCE flow yourself and paste the resulting access token in a Bearer header. Bash:

BASE="https://vantage-peers-production.up.railway.app"
CLIENT_ID="YOUR_CLIENT_ID"
CLIENT_SECRET="YOUR_CLIENT_SECRET"
REDIRECT="http://localhost:3000/callback"

# 1. PKCE verifier + challenge (S256)
VERIFIER=$(openssl rand -base64 64 | tr -d "=+/" | head -c 64)
CHALLENGE=$(printf "%s" "$VERIFIER" | openssl dgst -sha256 -binary | openssl base64 | tr -d "=" | tr "+/" "-_")

# 2. Print the authorize URL — open in a browser, accept consent, copy the `code` from the callback URL
echo "$BASE/oauth/authorize?response_type=code&client_id=$CLIENT_ID&redirect_uri=$REDIRECT&code_challenge=$CHALLENGE&code_challenge_method=S256&scope=mcp:full"

# 3. After consent, exchange the code for an access_token
read -p "Paste the code from the callback URL: " CODE
curl -s -X POST "$BASE/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=$CODE" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  -d "redirect_uri=$REDIRECT" \
  -d "code_verifier=$VERIFIER" | jq .

The response contains access_token (short-lived) and refresh_token. Send Authorization: Bearer <access_token> on every tool call.

Verify your install

Whichever client you used, these three calls must succeed:

• recall query="VantagePeers" — semantic search across your scope.
• list_tasks — your assigned tasks.
• list_memories namespace="global" — global memories (read-only public scope).

Troubleshooting

• 401 Unauthorized — access token expired or client_secret invalid. Refresh the token (clients do this automatically) or contact VantageOS to re-issue credentials.
• 403 Forbidden — your scope does not cover that resource. DCR-issued tokens default to client-generic (write to your tenant only). Read attempts on orchestrator/* namespaces outside your tenant return 403.
• 401 with WWW-Authenticate: Bearer resource_metadata="..." — your client should auto-discover the auth server and run the flow. If it does not, switch to manual config or pre-issued tokens.
• "Method not allowed" when uploading a file in Claude.ai — you are on Path 2 (web connector). Do not upload a plugin zip here. Use the MCP server URL instead (see Path 2 above).
• ChatGPT extra confirmation prompts — expected. They are driven by the per-tool destructiveHint and readOnlyHint annotations.

Help

• Documentation
• Changelog
• Support: via the channel agreed with VantageOS during your onboarding.