Skip to content
VivrealDocs

Connecting from Claude.ai

Self-serve install steps for the Vivreal MCP Server in Claude.ai or Claude Code

beginner4 min readFor developers

Connecting from Claude.ai

The Vivreal MCP Server works with any MCP-compatible client. The most common paths are Claude.ai (web/desktop) and Claude Code (CLI). Both use the same OAuth flow — the only difference is how you trigger the install.

Path 1 — Claude.ai (self-serve)

  1. Open Claude.ai (web or desktop).
  2. Go to Settings → Connectors → Add custom connector.
  3. Enter:
    • Name: Vivreal
    • URL: https://mcp.vivreal.io/mcp
  4. Click Connect. Claude.ai opens a browser tab to mcp.vivreal.io/oauth/authorize.
  5. The Vivreal login screen appears at https://auth.vivreal.io — the same Cognito Hosted UI you see when logging in at vivreal.io/app/login. Log in.
  6. Approve the scopes Claude is requesting: vivreal/cms.read and vivreal/cms.write. (Admin scope is only requested when an agent explicitly needs to mutate group membership or billing.)
  7. The tab closes; you're back in Claude.ai with the Vivreal connector active.
  8. Open a new chat and ask Claude to "list my Vivreal groups." It will call get-session-context, then set-active-group, then any tools you ask for.

Two callback URLs supported

Claude.ai's OAuth redirect lands at either https://claude.ai/api/mcp/auth_callback or https://claude.com/api/mcp/auth_callback depending on your region. Both are accepted by our authorization server without pre-registration — see OAuth & Scopes for the broker design.

Path 2 — Claude Code (CLI)

Install in one command:

claude mcp add --transport http vivreal https://mcp.vivreal.io/mcp

On first use, Claude Code opens a browser tab for the OAuth handshake — same UI as Claude.ai. Once authenticated, the session persists in your Claude Code profile.

To verify the install:

claude mcp list
# vivreal — https://mcp.vivreal.io/mcp (status: connected)

To remove:

claude mcp remove vivreal

Path 3 — Custom MCP client

Any client implementing MCP 2025-11-25 over HTTP works. Point it at https://mcp.vivreal.io/mcp and walk the OAuth flow against https://mcp.vivreal.io:

  • Discovery: GET /.well-known/oauth-protected-resource
  • Auth: GET /oauth/authorize (PKCE with S256)
  • Token: POST /oauth/token
  • DCR: POST /oauth/register (Dynamic Client Registration per RFC 7591)

See the OAuth & Scopes page for the full discovery payload and scope reference.

After You're Connected

You'll typically want to:

  1. List your groups — Claude calls get-session-context, returns the groups you belong to.
  2. Pick an active group — Claude calls set-active-group with the group ID. This is required before any CMS operation.
  3. Explore your content — try "list my content types" or "what's on my dashboard this week."

For curated agent workflows like "audit my group setup" or "post this to all my socials," see the Prompts section in your MCP client — the server ships 8 guided workflow prompts.

Troubleshooting

  • Connector says "failed to connect": check that https://mcp.vivreal.io/.well-known/oauth-protected-resource returns JSON in a browser. If it 404s, the deploy might be in flight — wait 1-2 minutes.
  • OAuth tab closes with no error: open Claude.ai's developer console and look for redirect_uri mismatches. The two valid Anthropic callbacks (claude.ai/api/mcp/auth_callback and claude.com/api/mcp/auth_callback) are both accepted; if you see a different host, check your Claude.ai region settings.
  • Tools call but always 401: your token may have expired. Disconnect + reconnect to force a fresh token. Tokens are 1-hour TTL; refresh tokens are 30 days.

See the Troubleshooting page for more.