Connect an MCP client · Vaakyo docs

The server URL is the same everywhere:

https://console.vaakyo.com/mcp

Each client below connects with OAuth: it opens a Vaakyo page where you sign in and choose Allow. If you belong to more than one workspace, pick the one to connect on that page.

Claude Code

claude mcp add --transport http vaakyo https://console.vaakyo.com/mcp

Then run /mcp inside Claude Code, pick voxa and choose Authenticate. Your browser opens the Vaakyo consent page.

To use an API key instead of signing in:

claude mcp add --transport http vaakyo https://console.vaakyo.com/mcp \
  --header "Authorization: Bearer $VAAKYO_API_KEY"

Claude Desktop and claude.ai

Open Settings → Connectors and choose Add custom connector.
Name it Vaakyo and paste https://console.vaakyo.com/mcp as the URL.
Choose Connect. Sign in to Vaakyo in the window that opens and choose Allow.

Custom connectors sign in with OAuth only; they can’t send an API key.

Cursor

Add Vaakyo to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "vaakyo": {
      "url": "https://console.vaakyo.com/mcp"
    }
  }
}

Open Cursor Settings → MCP. Vaakyo shows a Login button the first time; it opens the consent page.

With an API key instead, add "headers": { "Authorization": "Bearer vx_your_key" } next to url.

VS Code (GitHub Copilot)

Add a .vscode/mcp.json to your project:

{
  "servers": {
    "vaakyo": {
      "type": "http",
      "url": "https://console.vaakyo.com/mcp"
    }
  }
}

Start the server from the file (or MCP: List Servers in the command palette). VS Code asks you to sign in to Vaakyo in the browser.

Windsurf

Add Vaakyo to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "vaakyo": {
      "serverUrl": "https://console.vaakyo.com/mcp"
    }
  }
}

Any other client

Point it at https://console.vaakyo.com/mcp with the Streamable HTTP transport. Clients that follow the MCP authorization spec find everything on their own from the 401 response:

Endpoint	URL
Protected resource metadata	`https://console.vaakyo.com/.well-known/oauth-protected-resource/mcp`
Authorization server metadata	`https://console.vaakyo.com/.well-known/oauth-authorization-server`
Authorization (consent page)	`https://console.vaakyo.com/oauth/authorize`
Token	`https://api.vaakyo.com/api/oauth/token`
Client registration	`https://api.vaakyo.com/api/oauth/register`
Revocation	`https://api.vaakyo.com/api/oauth/revoke`

Vaakyo supports the authorization code grant with PKCE (S256 only), refresh tokens, and open dynamic client registration. Redirect URIs must be https, http on localhost/127.0.0.1, or an app’s own scheme (for example cursor://).

Scopes

Ask only for what your app needs, space-separated in the scope parameter. A token can never do more than the person’s role allows, nor more than an API key may.

Scope	Lets the app
`mcp`	Everything below (the default when no scope is sent)
`agents.view`	Read agents, their versions, knowledge bases and settings
`agents.edit`	Create, edit, publish and delete agents, tools and knowledge
`calls.view`	Read calls, transcripts, recordings, events and analytics
`calls.place`	Place, schedule and cancel calls and campaigns (uses credits)
`logs.view`	Read request and system logs
`members.view`	List the workspace’s members
`keys.manage`	Create and revoke API keys and webhooks
`billing.view`	Read the credit balance, plan, usage and limits

An unknown scope is refused with invalid_scope. The granted scope comes back in the token response (scope), and the OpenAPI spec lists the scope each operation needs (the OAuth2 security scheme).

A client that can’t register itself (some connector forms ask for a client ID up front) can register once by hand:

curl -X POST https://api.vaakyo.com/api/oauth/register \
  -H "Content-Type: application/json" \
  -d '{"client_name": "My agent", "redirect_uris": ["https://my-agent.example.com/oauth/callback"],
       "token_endpoint_auth_method": "client_secret_post"}'

The response holds the client_id (and a client_secret, shown once) to paste into the form.

To try the server by hand, run the MCP Inspector and connect it to the URL above:

npx @modelcontextprotocol/inspector

Check the connection

Ask your assistant:

List my Vaakyo agents and tell me which voice and model each one uses.

It calls list_agents and answers from your workspace. If it says it isn’t signed in, run the client’s sign-in step again; if the token was revoked under Settings → Connected apps, connect it again.

Troubleshooting

What you see	What to do
The browser never opens	The client may not support OAuth. Use an API key header, or another client.
“Can’t connect this app” on the consent page	The app’s registration is missing or its return address doesn’t match. Remove the server in the client and add it again.
“choose an active workspace first”	Your workspace is still in onboarding. Finish KYC, then connect.
`401` after it worked before	The connection was disconnected, or you left the workspace. Connect again.
`HTTP 403: your role cannot do this` from a tool	Your role can’t make that change (viewers only read). Ask an owner or admin.