📌 Looking for the install? The visual 3-step guide for Claude, Cursor, ChatGPT, and Manus is at getvamos.ai/mcp. This article is the technical reference — tools, limits, host quirks, billing, and troubleshooting.

The MCP tools

The Vamos MCP exposes the following tools. Your AI client picks the right one automatically based on what you ask — you don't call them directly.

Tool	What it does	Spends credits?
`chat_completion`	Runs a full Vamos AI chat turn synchronously — research, analysis, scripts, captions. Has access to all Vamos tools (video search across TikTok, Instagram, YouTube, LinkedIn, X, Facebook, and Threads; web search; profile and post analysis; comment pulls) and writes using your Brand Voice and Memory. Best for quick asks (under 30 seconds) on hosts that hold long connections (Claude Desktop, Claude Code).	Yes
`chat_completion_start`	Starts a Vamos turn in the background and returns a `runId` immediately. Default path for hosts that proxy MCP (claude.ai web, Claude Desktop, mobile, Manus, ChatGPT custom connectors) — those proxies drop long sync calls, and the async handle avoids that entirely.	Yes (on completion)
`chat_completion_poll`	Polls a `runId` for status; long-polls server-side so calls return as soon as status changes. Your client calls it back-to-back until the run is `done`, `failed`, or `cancelled`.	No
`chat_completion_cancel`	Aborts an in-flight run cleanly so credits stop accruing. Use when the user changes their mind mid-task.	No
`create_chat`	Starts a new Vamos conversation and returns its `chatId`.	No
`list_chats`	Lists your existing Vamos chats so the AI can continue an earlier conversation instead of starting fresh.	No
`get_messages`	Reads message history from a chat — useful for follow-ups, summarising past research, or checking whether a timed-out turn already completed server-side before retrying.	No
`get_credit_usage`	Returns your remaining workspace credits and plan tier.	No
`auth_status`	Reports whether the current session is authenticated to Vamos. Returns the authorization URL if not — useful when a host's OAuth flow hiccups and the AI needs to surface the sign-in link.	No

You don't call these directly. You just chat with your AI — "use Vamos to find the top 10 finance Reels this week" — and the client picks the right tool.

The using-vamos Skill (recommended for Claude Code)

If you're using Claude Code, install the using-vamos skill alongside the MCP. It teaches Claude how to call Vamos well — chat continuity, content shape, multi-turn handling, and how to surface Vamos's response cleanly.

Without the skill, Claude still uses the MCP — but the skill encodes the calling patterns that make the difference between "Vamos returned generic" and "Vamos nailed it."

Install in 3 steps:

Download the skill from getvamos.ai/skill
Place the file at ~/.claude/skills/using-vamos/SKILL.md
Restart Claude Code. The skill auto-activates whenever you ask about social media — captions, hooks, scripts, research, competitor or trend analysis, comment pulls.

What the skill does internally:

Calls list_chats first to continue an existing Vamos chat instead of starting a fresh one each time
Picks the right completion tool — chat_completion_start + chat_completion_poll for anything substantial, sync chat_completion only for sub-30-second asks
Folds multi-part requests into a single completion instead of fanning out parallel calls
Strips out filler before passing your request — keeps the prompt focused, no hallucinated handles or pre-seeded creator lists
Passes Vamos's output through to the user with at most a short framing line, instead of rewriting it in your own voice
Handles ERR_TIMEOUT by calling get_messages first to check if the turn already completed server-side, then retrying with the same chatId if it didn't — never blind-retries
Surfaces the authorization_url from auth errors directly to the user instead of inventing dashboard navigation steps

Currently the skill is Claude-Code-specific. Skill support in Claude Desktop, Cursor, ChatGPT, and Manus is on the way.

What you can't do (yet)

No image generation, file upload, or Canvas edits. Those stay in the Vamos web app at app.getvamos.ai.
No streaming text. Vamos returns the full answer once the agent finishes (30 sec – 10 min depending on the task). Some clients show progress, some go silent until done — see the host compatibility table below.
No raw tool results. The MCP returns the agent's prose. Full search-result JSON, transcripts, and comment dumps live only inside the chat in app.getvamos.ai.
No workspace switching mid-session. The token is bound to your active workspace at sign-in. Switched workspaces in the Vamos app? Sign out and back in inside your AI client to refresh.
Not idempotent. Retrying chat_completion re-runs the agent and re-bills credits. On ERR_TIMEOUT, call get_messages first to check if the turn already completed — don't blind-retry.
Long-run handling. Sync chat_completion caps at ~10 minutes — runs that hit the cap are preserved in app.getvamos.ai, where you can open the chat and continue. Async runs (chat_completion_start) carry no client-side cap and surface results via polling — no proxy drop, no lost progress.

Host compatibility

Not every AI client treats long-running tools the same. Use this to set expectations.

Client	Live progress?	UX on long tasks
Claude Desktop	Yes	Shows live progress mid-call
Claude Code	Yes	Shows live progress mid-call (best UX, especially with the `using-vamos` skill)
Cursor	Minimal	Shows little until done
ChatGPT	No	Silent until result returns — expect up to 10 minutes on heavy prompts
Manus / autonomous agents	Varies	May retry aggressively — re-bills credits per retry. Set a retry cap in your agent config.
Codex	Partial	Depends on the version

Tip: on ChatGPT and Cursor, expect up to 10 minutes of silence on heavy research prompts. Break large requests into smaller asks.

Common workflows

Five patterns that come up over and over.

1. Research while you're already coding or writing

You're in Claude Code building something and need creator data:

"Use Vamos to find the top 5 TikToks about morning routines this month and summarise the hooks."

Vamos runs the search, returns the analysis, and Claude keeps coding with that context.

2. Generate a script in your Brand Voice

"Use Vamos to write a 60-second YouTube Short script about productivity, in my voice."

Brand Voice and Memory load automatically — no toggles, no pasted samples.

3. Continue an existing Vamos chat

"List my recent Vamos chats and continue the one about the launch campaign."

The AI calls list_chats, picks the right one, and resumes from there. The using-vamos skill does this automatically — see the Skill section above.

4. Competitor deep-dive

"Pull @[creator]'s last 30 Reels via Vamos, analyze hook patterns, and tell me what they're testing."

5. Check credits before a heavy task

"What's my Vamos credit balance?" → the AI calls get_credit_usage.

Billing & credits

MCP calls run on your workspace credits — same pool as the web app.
Pricing matches the web app — the MCP doesn't cost extra. AUTO model selection still applies.
Read-only tools (list_chats, get_messages, get_credit_usage, chat_completion_poll, chat_completion_cancel, auth_status) don't deduct credits. Only chat_completion and chat_completion_start spend — and chat_completion_start bills when the run completes, even if you stop polling. Use chat_completion_cancel to abort cleanly.
Run out of credits? The tool returns ERR_INSUFFICIENT_CREDITS — top up at Settings → Billing.

Troubleshooting & advanced FAQ

I switched workspaces in the Vamos app — why is the AI still writing for the old one?
The MCP token is bound to your active workspace at sign-in. Sign out of the Vamos MCP in your AI client and reconnect.

Can I revoke access?
Yes — sign out of the MCP server inside your AI client, or contact us to revoke server-side.

Does it support team / multi-user setups?
Each user authenticates with their own Vamos account, so each teammate connects independently. There's no shared MCP key.

Which Vamos plan do I need?
Any paid plan with credits. The MCP is included on Pro and Business. Free / trial accounts can use it while trial credits last.

My Manus agent burns through credits — what's happening?
Manus and other autonomous agents retry failed calls automatically. Each retry re-runs chat_completion and re-bills. Set a retry cap of 1 in your agent config, or use a different client for heavy research tasks.

I'm using Cursor and it looks like nothing's happening.
Cursor doesn't show MCP tool progress mid-call. The agent IS running — give it up to 10 minutes. If it still hasn't returned, check your credit balance and Vamos status page.

The skill isn't activating in Claude Code.
Check that SKILL.md is at exactly ~/.claude/skills/using-vamos/SKILL.md and you've restarted Claude Code. The skill activates by description matching — ask something explicitly social-media-related ("use Vamos to find...") rather than generic.

The AI told me to "open my dashboard and navigate to Settings → Integrations" but that's not where I sign in to Vamos.
Your MCP host has hit an auth error and didn't surface the real sign-in URL. The MCP returns the URL in the error body and via the auth_status tool — ask the AI to call auth_status, or sign out and reconnect in your client's MCP / connector settings.

Questions? Chat widget or [email protected].

Frequently asked questions (FAQ)

Vamos MCP — Technical reference