Skip to content
Voyage MCP

Authentication

Overview

Section titled “Overview”

Voyage MCP uses OAuth 2.1 with PKCE to securely connect your MCP client (Claude Code, Claude Desktop, Cursor) to your Voyage account. This is the same industry-standard protocol used by major platforms — your credentials are never shared with the MCP client.

How it works

Section titled “How it works”

When you first use a Voyage tool, the following happens automatically:

  1. Connect Your MCP client discovers the Voyage MCP server and initiates an OAuth flow.

  2. Log in A browser window opens to the Voyage login page. Log in with your existing Voyage credentials.

  3. Select brand Choose which brand you want to connect. Your MCP session will be scoped to this brand.

  4. Approve Review the requested permissions and approve the connection.

  5. Connected Your MCP client receives an access token and can now use Voyage tools on your behalf.

Token management

Section titled “Token management”
  • Access tokens are short-lived and scoped to the mcp:tools permission
  • Refresh tokens allow your client to get new access tokens automatically — you won’t need to re-authenticate during a session
  • Brand context is embedded in the token — all tool calls operate on the brand you selected during login

Scopes

Section titled “Scopes”
ScopeDescription
mcp:toolsAccess to all brand-scoped MCP tools

Security

Section titled “Security”
  • PKCE (Proof Key for Code Exchange) prevents authorization code interception
  • Read-only — MCP tools only read data, they never modify your Voyage account
  • Brand-scoped — You can only access data for the brand you selected during authentication
  • No credentials shared — Your Voyage password is entered directly on the Voyage login page, never passed through the MCP client

Troubleshooting

Section titled “Troubleshooting”

Browser doesn’t open during authentication

Your MCP client should automatically open a browser window. If it doesn’t, check the terminal output for a URL you can copy and paste manually.

“Unauthorized” errors after connecting

Your access token may have expired and failed to refresh. Disconnect and reconnect to re-authenticate:

  • Claude Code: claude mcp remove voyage then re-add
  • Claude Desktop / Cursor: Restart the application

“Brand context required” errors

This means authentication succeeded but no brand was selected. Reconnect and make sure to select a brand during the approval step.