Connecting an AI assistant

Vaam’s MCP server lives at one address:

https://app.vaam.io/api/agent/mcp

That single URL is all most assistants need. You paste it into the assistant, log in with your normal Vaam account, approve the permissions, and you are connected. Vaam runs its own login and approval screens, so you never create an app registration, a client ID, or a client secret.

There are two ways to authenticate:

• Log in through your assistant — the right choice for Claude, ChatGPT, and anything else you chat with. Covered in the walkthroughs below.
• An API key — the right choice for scripts, backend jobs, and agents you build yourself. See Scripts and custom agents.

Claude (claude.ai, Claude Desktop, and mobile)

You add the connector once for your Claude account, and it becomes available in the Claude web app, Claude Desktop, and the mobile apps.

1. Go to Customize → Connectors at claude.ai/customize/connectors.
2. Click ”+”, then Add custom connector.
3. Paste https://app.vaam.io/api/agent/mcp as the remote MCP server URL.
4. Leave the OAuth Client ID and Client Secret fields under Advanced settings empty. Vaam registers Claude automatically, so you do not need them.
5. Click Add, then follow Claude’s prompt to connect. Claude opens Vaam in a browser tab. Log in if you are not already logged in, then approve the request on Vaam’s approval screen.
6. Back in a chat, turn the connector on for the conversation with the ”+” button, then Connectors.

Ask “What’s my outreach status in Vaam?” to confirm it works.

On Team and Enterprise plans, an Owner adds the connector once under Organization settings → Connectors, and every member then connects with their own Vaam account. Each person only ever sees what their own Vaam account can see.

For the current Claude interface, see Anthropic’s own guide: Get started with custom connectors using remote MCP.

Claude Code

Add the server from your terminal:

claude mcp add --transport http vaam https://app.vaam.io/api/agent/mcp

By default the server is available in the current project only. Add --scope user to make it available in all your projects:

claude mcp add --transport http --scope user vaam https://app.vaam.io/api/agent/mcp

Then authenticate:

1. Run /mcp inside Claude Code.
2. Choose the vaam server and start the login.
3. Your browser opens Vaam. Log in, then approve the request on the approval screen.
4. Claude Code stores the tokens and refreshes them for you.

If the browser does not open, copy the URL that Claude Code prints and open it yourself. If the redirect back to Claude Code fails, paste the full callback URL from your browser’s address bar into the prompt that Claude Code shows.

To sign out again, run /mcp and choose Clear authentication for the vaam server.

ChatGPT (developer mode)

Custom MCP servers in ChatGPT need developer mode, which is available on Pro, Plus, Business, Enterprise, and Education accounts on the web.

1. Open Settings → Security and login and turn on Developer mode.
2. Create a new developer-mode app and give it https://app.vaam.io/api/agent/mcp as the server URL.
3. Choose OAuth as the authentication method. Leave any client ID and client secret fields empty — Vaam registers ChatGPT automatically.
4. Complete the login and approve the request on Vaam’s approval screen.
5. Turn the app on for a conversation from the ”+” menu.

OpenAI changes this interface regularly, so follow their current instructions for the exact screens: Developer mode and MCP apps in ChatGPT.

A custom or programmatic client

You can drive the same login flow from your own MCP client. Vaam is a standard OAuth 2.1 authorization server with PKCE, and it publishes everything a client needs to discover on its own:

What	Where
Which authorization server to use	https://app.vaam.io/api/agent/.well-known/oauth-protected-resource
Login, token, and registration endpoints	https://app.vaam.io/api/agent/oauth/.well-known/oauth-authorization-server

A client that follows the MCP specification finds both by itself: an unauthenticated request to the server returns 401 with a WWW-Authenticate header pointing at the first URL, which points at the second.

Four things Vaam requires:

• PKCE with S256. Plain code challenges are rejected.
• No client secret. Clients are public. Sending a client secret or an Authorization header to the token endpoint fails with invalid_client.
• Registration first. Your client registers itself at the registration endpoint and gets a client ID back. There is no manual app registration in Vaam.
• A supported callback URL. For a client running on your own machine, the callback must be exactly http://localhost:<port>/callback, http://127.0.0.1:<port>/callback, or http://[::1]:<port>/callback. The port can be anything and can change between runs, but the path must be /callback. Any other path or host is rejected at registration.

That last rule is the one custom clients trip over. If your client insists on a different callback path, or it runs on a server rather than a laptop, use an API key instead.

The MCP Inspector is a quick way to check the flow end to end before you write code — it uses a http://localhost:<port>/callback redirect, so it works as-is.

Scripts and custom agents

For a reporting job, a backend integration, or an agent you build yourself, an API key is simpler than a login flow.

1. In Vaam, go to Settings → API.
2. Click Create API key.
3. Give it a name you will recognise later, such as “Weekly reporting sync”.
4. Tick only the permissions the integration needs. Read access and Write access are the two groups, and you can tick individual permissions inside each. A reporting job needs no write permissions at all.
5. Click Create key. The key is copied to your clipboard and shown once. Copy it now — you cannot see it again. Store it the way you store any other password.

The key starts with vaam_sk_ and goes in the Authorization header on every request.

A worked example

Vaam shows you this configuration right after it creates the key. Paste it into any MCP client that reads an mcpServers config file:

{
  "mcpServers": {
    "vaam": {
      "url": "https://app.vaam.io/api/agent/mcp",
      "headers": {
        "Authorization": "Bearer vaam_sk_..."
      }
    }
  }
}

If you are calling the server directly rather than through an MCP client library, it speaks JSON-RPC over HTTP POST. This lists the tools your key can reach:

curl -sS https://app.vaam.io/api/agent/mcp \
  -H "Authorization: Bearer $VAAM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

And this asks for your account totals:

curl -sS https://app.vaam.io/api/agent/mcp \
  -H "Authorization: Bearer $VAAM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"get_stats","arguments":{}}}'

Send both Accept values. The transport may answer as plain JSON or as a stream, and listing both lets it choose.

To retire a key, go back to Settings → API and delete it. Anything still using that key stops working immediately, so check before you delete.

What the approval screen shows

Every login ends on a Vaam page that asks you to approve the connection. It shows three things, and all three are worth reading:

• Which assistant is asking. The heading names the assistant, and the line below it shows the web address that will receive the access. The name comes from the assistant itself, so treat the address as the fact and the name as a label. If you started this from Claude, the address should be a claude.ai or claude.com one.
• Which Vaam account. Your email address. If it is the wrong account, stop, log out of Vaam, and start again.
• What the assistant will be able to do. A checklist of permissions, in plain terms. Permissions and trust explains what each line covers.

Then you choose Allow access or Deny. Nothing is granted until you click Allow access, and denying simply returns you to the assistant with no connection made.

Two things the screen deliberately does not do: it does not let the assistant pick a different account, and it does not let it ask for more than your own account can do. A connection can never grant more than you have.

Staying connected

Once you approve, the assistant holds a short-lived access token and a long-lived renewal token.

• The access token lasts one hour. Your assistant renews it in the background, so you will not notice.
• Each renewal issues a fresh renewal token and retires the old one. This is normal and automatic.
• As long as the assistant keeps renewing, the connection lasts. A connection that goes completely unused for 90 days expires, and you approve it again the next time you use it.

You may occasionally be asked to approve again after an interruption — for example if a renewal is attempted twice. That is the connection being cautious, not a sign that anything is wrong. Approve it again and carry on.

Disconnecting

Remove the connection from the assistant that holds it:

• claude.ai, Claude Desktop, mobile — Customize → Connectors, then Remove (or the three dots next to the connector). On Team and Enterprise plans an Owner removes it for the organization under Organization settings → Connectors.
• Claude Code — run /mcp, choose the vaam server, then Clear authentication. Use claude mcp remove vaam to drop the server entirely.
• ChatGPT — remove the app from your developer-mode app settings.
• An API key — delete it under Settings → API.

Removing the connector deletes the tokens the assistant was holding, so it can no longer reach Vaam. Vaam does not yet show a list of connected assistants inside the app. If you think a connection has been misused, or you cannot reach the assistant that holds it, email support@vaam.io and we will cut it off from our side.

When access ends, the assistant simply loses the Vaam tools. It does not lose its chat history, and nothing in your Vaam account changes. Anything the assistant already did — a paused sequence, an added prospect — stays done. Work that was already running in Vaam keeps running; a connected assistant starts and stops outreach, it does not perform it.

When something goes wrong

The assistant says it is not authorised, or asks you to log in again. Access ended. The usual causes are a connection removed somewhere else, a deleted API key, or a connection left unused past 90 days. Reconnect with the walkthrough for your assistant.

The connector connects but shows no tools. The connection succeeded but the tool list did not load. Refresh the connector in the assistant’s settings, or turn it off and on again for the conversation. If the list is still empty, disconnect and reconnect.

A tool refuses to make a change. The response names a missing permission. An API key only carries the permissions you ticked when you created it, and permissions cannot be added to an existing key. Create a new key with the permissions you need, swap it in, then delete the old one.

Everything slows down or fails with “too many requests”. You hit a rate limit. Wait for the time the response asks for, then continue. See Rate limits for the numbers and for how to pace a large job.

The assistant picks the wrong tool, or gives a number you do not recognise. Name what you want more precisely — “how many prospects are active in sequences right now” rather than “how am I doing”. If a count looks wrong, Paging through data and bulk sync explains why two tools can report different numbers for what sounds like the same question.

A custom client fails during login. Check the callback URL first. It must end in /callback on localhost, 127.0.0.1, or [::1]. See A custom or programmatic client.

Related

• Permissions and trust — what a connected assistant can and cannot see.
• What your assistant can do — the full tool list.
• Rate limits — request budgets and 429 handling.