Skip to content
Vaam Docs

Connecting an AI assistant

There are two ways to authenticate against Vaam’s MCP server at https://app.vaam.io/api/agent/mcp: OAuth (best for chat assistants) and API keys (best for integrations and custom agents).

Section titled “Option 1: OAuth (recommended for assistants)”

Assistants that support remote MCP servers — such as Claude and ChatGPT — can connect with OAuth. You add the server URL in the assistant’s connector or integration settings, and it walks you through logging in with your Vaam account:

  1. In your assistant, add a custom connector / MCP server with the URL https://app.vaam.io/api/agent/mcp.
  2. When prompted, log in with your Vaam account and approve the requested permissions.
  3. Ask something like “What’s my outreach status in Vaam?” to confirm it works.

The assistant acts as you: it sees your own data by default, and your team’s data only when a request is explicitly about the team.

Option 2: API key (for integrations and custom agents)

Section titled “Option 2: API key (for integrations and custom agents)”

For scripts, backend integrations, or agents you build yourself, use a scoped API key:

  1. In Vaam, go to Settings → API (app.vaam.io/settings/api).
  2. Create a new scoped key. Select only the permissions your integration needs — for example, a read-only reporting sync needs no write scopes.
  3. Copy the key (it starts with vaam_sk_) and store it securely. Treat it like a password.

Send the key as a bearer token on every request:

Authorization: Bearer vaam_sk_...

Scopes

Section titled “Scopes”

Each key carries an explicit list of permissions. Read scopes cover sequences, prospects, sequence progress, videos, stats, work items, and user/team/settings info; write scopes are separate and opt-in. Calls outside the key’s scopes fail with an error naming the missing scope — create a new key with the right scopes if you hit one.

Troubleshooting

Section titled “Troubleshooting”
  • 401 Authentication required — the Authorization header is missing or the key/token is invalid or revoked. Reconnect (OAuth) or check the key.
  • Insufficient scope — the key lacks a permission the tool needs. Create a key with the required scopes.
  • 429 Too many requests — you hit a rate limit; see rate limits.