Authentication

The vTilt MCP server accepts two equally valid authentication paths. Pick whichever fits your client:

Both paths grant the same access to the same projects you see in the dashboard. The rest of this page covers personal API keys — for OAuth, see the dedicated OAuth guide.

#1. Create a key

1. Sign in to your vTilt dashboard.
2. Open the user menu (top-right) and choose Personal API keys, or visit Account → Personal API keys directly.
3. Click Create key.
4. Give it a name that identifies the client and machine — e.g. Cursor on laptop, Claude Desktop on home Mac, Codex CLI on prod-runner.
5. Pick an access level:
   • Read-only (recommended) — the agent can list and inspect data through every read tool: get_kpis, list_persons, list_recent_events, list_recordings, the VQL query layer, and search_docs. This is the right choice for almost every workflow.
   • Read + write — adds the ability to mutate project state through write tools (update_project plus the Google Ads write surface). Every write call is recorded in the MCP audit log. Pick this only if you actively need the agent to change state on your behalf.
6. Click Create. The full secret (vtu_…) is shown once.
7. Copy it now and paste it into your client. After you close the modal the secret cannot be recovered.

If you lose the secret, revoke the key (it stays in the list with a revokedAt timestamp for audit purposes) and create a new one. Old keys keep working until they're revoked.

#2. What a key can do

A vtu_ key inherits all the projects you can see in the dashboard. Keys are scoped:

When the public REST API ships, you'll be able to mint keys with scope.mode = 'rest'; that selector isn't surfaced yet because there's no public REST surface to call.

#3. Use a key

Pass the secret as a Bearer token. Every MCP client supports headers:

# Health check — verify the key works before configuring a client.
# `tools/list` is an MCP method that returns the tool registry.
curl -X POST 'https://www.vtilt.com/api/mcp' \
  -H 'Authorization: Bearer vtu_YOUR_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

A successful response lists all tools the key can see (filtered by your access scope). If the response contains "error":{"code":-32001 or HTTP 401, the bearer header is missing, malformed, or revoked.

#4. Pin a project

If you have access to multiple projects, the server cannot guess which one you mean. Three ways to pin:

Optional fourth header — x-vtilt-mcp-session-id: <uuid> — partitions Redis session pins when several MCP connections share the same user credential. See MCP server overview and the Cursor guide's subsection on parallel chats.

Examples:

# Header (Cursor, Claude Desktop, VS Code all expose a "headers" field)
x-vtilt-project-id: 7c5c1a3a-9d62-4e09-8a4f-9a3ce1b1f4a8

# Optional — isolate switch_project pins per MCP connection (UUID)
x-vtilt-mcp-session-id: f47ac10b-58cc-4372-a567-0e02b2c3d479

# Query parameter
https://www.vtilt.com/api/mcp?project_id=7c5c1a3a-9d62-4e09-8a4f-9a3ce1b1f4a8

# Session pin via tool call (the agent does this for you)
> "Switch me to the Marketing site project."

You can find a project's id at Project settings → General in the dashboard. Single-project users don't need to pin — the server picks your only project automatically.

#5. Rotate and revoke

• Open Account → Personal API keys.
• Click Revoke next to the key. The row stays in the list (greyed out, with a revokedAt timestamp) so you can audit which keys existed when. Revoked keys reject every subsequent request with unauthorized.
• To rotate, create a new key first, swap it into your client, then revoke the old one.

#6. Common errors

#Next steps

• OAuth — the browser sign-in flow for modern MCP clients (recommended).
• Cursor — install in 30 seconds via the Cursor MCP catalogue or ~/.cursor/mcp.json.
• Claude Desktop — connect via OAuth or the mcp-remote bridge.
• VS Code — drop into .vscode/mcp.json.
• Codex — codex mcp add one-liner.