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, 84 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".

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.