MCP server

The vTilt MCP server lets your AI client — Cursor, Claude Desktop (via mcp-remote), VS Code, ChatGPT, Codex, custom agents — talk directly to your vTilt project data over the Model Context Protocol. The agent calls tools like get_kpis, list_persons, run_query, or query_ai_memory; vTilt runs them with the same privileges your dashboard uses, scoped to whatever project you've pinned. Almost every tool is read-only; update_project is the only core write tool today (Google Ads adds its own write surface), and only credentials minted with explicit write access can see or invoke it.

#Documentation map

Use the sidebar Guides and Client setup groups the same way as this table: concepts first, then wire your editor.

#Toolsets — grouping the tool surface

To keep the tool list small and focused (and to scale as we add product surfaces like Google Ads), tools are grouped into toolsets. A fresh connection boots with only the always-on and default toolsets — roughly a dozen tools — and everything else is one enable_toolset call away. This mirrors the dynamic-toolset model used by GitHub's and other large MCP servers: a small, self-describing default surface that an agent expands on demand.

Discover-then-enable flow — the three meta tools are always present:

1. list_toolsets — every toolset, its description, tool count, and whether it's currently enabled.
2. get_toolset { toolset } — preview a toolset's tools (names + descriptions + input schemas) without enabling it.
3. enable_toolset { toolset } (or { toolsets: [...] }) — enable one or more for this session. The tools are returned inline as a preview and the enabled set is persisted in your MCP session (Redis, 30-day TTL).

#Supported tools

The server defines 35 core tools across the toolsets above, plus the Google Ads toolsets (13 core + 16 typed write shortcuts) that become callable once a Google Ads account is connected. Each tool exposes both an input schema (the arguments it accepts) and an output schema (the shape of its successful result) over MCP tools/list, so your agent can reason about the data it's about to receive without first making a probe call. Successful responses are validated server-side against the output schema before they leave vTilt — if a tool ever returns a payload that doesn't match its declared shape, the call surfaces as an error rather than a malformed result.

The catalog spans orientation (get_guide, get_data_model, get_context), analytics & events, persons, session recordings, campaigns, event destinations, the open-ended VQL query layer (including AI memory tables when enabled), natural-language AI intelligence helpers, site knowledge (semantic search, page reads, change history + impact attribution, and structured element inventory over your indexed website), the public-docs reader (search_docs), project metadata + configuration + writes + navigation, and — when connected — Google Ads account reads and writes. switch_project, feature-gated tools, and write tools are omitted from the list when they cannot apply (see the notes after the table).

#What you can ask

These prompts work as soon as the server is connected and a project is pinned:

The agent picks the tools, the project, and the time ranges automatically — you just describe what you want.

#How it works

Your AI client (Cursor / Claude Desktop / ChatGPT / …)
        │
        ▼   POST https://www.vtilt.com/api/mcp + Authorization: Bearer vtu_…
vTilt MCP server (hosted)
        │
        ▼
Tool registry  ──►  Entity action  ──►  Postgres / ClickHouse / Redis

Three properties matter:

1. Reads are read-only; writes are explicit and audited. The read tools touch no customer data and write nothing to your account except a per-lane "pinned project" pointer and your enabled-toolset set in Redis (see Pinning a project). The first core write tool (update_project) requires a personal API key created with Read + write access (or an OAuth token with the mcp:write scope) — it isn't visible to read-only credentials at all. Every write call lands a durable row in the MCP audit log so admins can answer "who renamed this project?" months later.
2. It's scoped to your projects. A vtu_ key is owned by you, not by a project. Tools resolve the active project from a header, query parameter, or per-lane session pin — you can switch projects mid-conversation with switch_project.
3. You control the budget. Every key counts against a 60-tool-call-per-minute sliding window. The connection handshake and discovery calls (initialize, tools/list, resources/*, prompts/list) are exempt, so reconnecting never burns your budget. Hit the limit and the next call returns a JSON-RPC error with a retryAfter hint.

#Connect a client

#Pinning a project

Most clients let you pass headers or query parameters per connection. vTilt accepts:

If you only have one project, you don't need to pin anything — the server auto-pins to your single project.

#Switching projects conversationally

You don't need to copy a UUID from the dashboard — once the MCP server is connected, just say what you want:

"What's last week's bounce rate on the Marketing site?"

The agent will:

1. Call list_projects to resolve the name to a UUID (and see which project is currently pinned).
2. Call the analytics tool with a per-call project_id for Marketing site — the sticky pin is left alone.
3. If you keep working on that project, it should ask before calling switch_project to make the pin sticky for the rest of the chat.

When you explicitly want a sticky switch:

"Switch to the Marketing site project and keep working there."

…the agent calls switch_project with { "project_name": "Marketing site" } (fuzzy match; ambiguous names return candidates). If the agent already has the UUID, project_id is preferred.

#Parallel chats on one MCP config

If the same MCP entry in your mcp.json powers several chats at once (Cursor tabs, VS Code chats, cloud agents) and each chat is working on a different project, switch_project is the wrong tool — its Redis session pin is shared across the connection and concurrent calls overwrite each other. Pick one of:

• Per-call project_id (recommended). Every data tool — get_kpis, list_recent_events, list_persons, run_query, update_project, … — accepts an optional project_id argument that overrides the active project for that single call only. The session pin is not touched, so two chats can hit different projects on one MCP config without racing. Ask each chat "work on the Marketing project" / "work on the Product project" and the agent will append project_id automatically.
• One-off comparisons ("compare Marketing and Product"). Same pattern — pass project_id per call instead of switch_project-ing back and forth. The audit log records the effective project per row (project_id_source = 'param' for overrides, 'session' / 'default' for pin-path reads).
• Distinct lane UUIDs — for older agents that don't pass project_id per call, add a different x-vtilt-mcp-session-id per duplicate server entry so each connection gets its own Redis pin namespace (Cursor shows the exact JSON).
• Per-project server entries — register vtilt-marketing and vtilt-product as separate MCP servers, each with its own static x-vtilt-project-id header. Useful when the integrator wants a hard guarantee that one connection never touches the other project.

#Querying with VQL

The three query tools (run_query, validate_query, get_query_schema) let an agent ask questions that don't fit the curated readers — funnels, custom segmentation, joins between events and persons, and (when AI memory is enabled) semantic search over distilled sessions, chats, recordings, and per-person intelligence. They share one pipeline (the VQL compiler) that enforces tenant scoping, read-only safety, and per-table permissions before any SQL touches ClickHouse. Vector similarity uses the :embed('text') macro documented on AI intelligence.

#What VQL is

A controlled subset of ClickHouse SQL:

• Single SELECT statement (with optional WITH / CTEs, JOIN, GROUP BY, window functions). No INSERT, UPDATE, DELETE, CREATE, ALTER, SET, etc. Multi-statement input is rejected.
• Curated catalog of virtual tables — analytics core (events, persons, person_distinct_ids, person_overrides) plus AI memory tables such as session_summaries and person_memory_latest when your project has AI memory turned on. Database-qualified names (system.users) and table functions (remote(), s3(), file()) are blocked at compile time. get_query_schema is the source of truth for the exact table and column list your caller can use.
• Curated function allowlist — standard aggregations (count, sum, uniq, quantile*), JSON helpers (JSONExtract*), date helpers (toStartOfDay, dateDiff, now), string / array / conditional functions, and the vector distance family (cosineDistance, L2Distance, L2SquaredDistance, dotProduct) where embeddings exist. System / cluster / file / dictionary functions are rejected.
• Tenant scoping is automatic. The server applies a project_id filter to every catalog table at the storage engine level (ClickHouse additional_table_filters). Do not add project_id to your WHERE clause — you'd be filtering an already-filtered set.
• Hard ceilings. readonly = 2, 30s execution timeout, 50M-row scan cap, 1000-row result cap (clamp the result smaller via limit).

#Tools

The recommended agent loop is get_query_schema → write VQL → validate_query → fix any errors using the structured code + hint → run_query. The validate step is cheap (no ClickHouse round-trip) and catches almost every class of failure agents make.

#$autocapture clicks in tool responses

The browser SDK stores compact autocapture: $elements_chain (encoded string) plus $el_text, not the verbose $elements array. ClickHouse keeps that shape; MCP tools enrich at read time:

$element and $elements_chain describe DOM structure (tag, classes, attr__* HTML attributes). Many sites attach additional business metadata that lives as top-level keys on properties — especially data-vt-capture-attribute-* (promoted to keys like feature, variant) and flags such as $external_click_url. Do not stop at $element; scan the full properties object on every $autocapture row.

Do not JSON.parse($elements_chain) or expect properties.$elements on modern sites. Invoke /vtilt:conventions for the full data-model rules.

#Permissions

VQL enforces permissions per referenced table. The matrix below is the analytics core; AI memory tables (session_summaries, conversation_summaries, recording_summaries, person_memory_latest, ai_usage_log) each carry their own requirement — see the table on AI intelligence. The query toolset is enabled by default, so these tools are in the boot set.

Org owners and admins always pass. A regular member sees permission_denied from run_query / validate_query and gets the table omitted from get_query_schema if they lack the permission for it. The query trio enforces the per-table check at compile time, not at registry-filter time.

#Example: pageviews per day, last 14 days

Find the top 10 distinct ids by pageview count over the last 14 days,
ordered descending. Use VQL.

The agent will typically call get_query_schema, write something like:

SELECT distinct_id, count() AS pageviews
FROM events
WHERE event = '$pageview'
  AND timestamp > now() - INTERVAL 14 DAY
GROUP BY distinct_id
ORDER BY pageviews DESC
LIMIT 10

…then validate_query (catches typos / unknown columns), then run_query. Note the absence of any project_id clause — the server injects it.

#Error envelope

validate_query returns { valid: false, error: { code, message, position?, hint? } } when the compiler rejects the SQL — the tool call itself succeeded; read error.code and error.hint to fix the query.

run_query uses two shapes:

• Compile failure (bad syntax, unknown table/column, permission denied at compile time) — { ok: false, error: { … } } in the normal tool result, same error object as above. MCP clients surface this in structuredContent instead of collapsing it to "Error occurred during tool execution".
• Runtime failure (query compiled but ClickHouse rejected it) — { error: { code: "invalid_arguments", message, next, details: { vql: { code: "execution_error", … } } } } on isError: true.

{
  "ok": false,
  "error": {
    "code": "unknown_table",
    "message": "Unknown table: secret_internal_table.",
    "hint": "Call get_query_schema for the catalog of virtual tables your credential can access."
  }
}

Stable VQL error.code values: parse_error, unsupported_statement, unsupported_construct, unknown_table, unknown_function, permission_denied, execution_error, plus embed-specific codes (embed_invalid_argument, embed_text_too_long, embed_disabled) described on AI intelligence. Agents pattern-match on code to self-correct (e.g. parse_error → re-read the syntax; unknown_table → call get_query_schema; permission_denied → ask a project admin or pick a different table).

Every other tool follows the same idea with a slightly richer envelope so agents can recover in one turn:

{
  "error": {
    "code": "project_not_found",
    "message": "No accessible project matches \"markting site\".",
    "next": "list_projects, switch_project",
    "details": { "suggestions": ["Marketing site", "Marketing app"] }
  }
}

code is one of no_active_project, project_not_found, project_ambiguous, permission_denied, feature_disabled, resource_not_found, invalid_arguments, internal_error. next names the tool(s) to call to recover, and details carries actionable structure (closest project names, the missing permission, the disabled feature). The agent reads next and details and retries without asking you.

#Searching the docs from your agent

The search_docs tool gives your AI client access to the same documentation corpus that powers /docs, /llms.txt, and /llms-full.txt. Use it when you'd otherwise paste a doc link into the conversation — the agent grabs the relevant snippet itself and can keep working without context-switching.

Input: { query: string, limit?: number (default 5, max 15) }. Output: { results: Array<{ title, slug, url, description, snippet, score }>, total_matched: number }.

{
  "query": "how do I configure event forwarding to GA4?",
  "limit": 3
}

Returns matched pages with body excerpts and absolute URLs (https://www.vtilt.com/docs/guides/event-forwarding). The tool runs in-process — no third-party search service — so results are deterministic and self-host installations get the same surface for free.

"Where do I put my project token in a Next.js app? Show me the exact code."

…will typically call search_docs with the question, then weave the matched code samples into the response.

#Writing data

vTilt's core MCP surface is mostly read-only by design — the curated readers and the VQL query layer cover almost every "summarise / analyse / explore" prompt without touching tenant state. The first core write tool, update_project (in the on-demand project toolset), ships with three-layer safety (the Google Ads write tools follow the same model):

1. Scoped credentials. Read-only personal API keys (the default when you create a key) and OAuth tokens without mcp:write never see write tools in tools/list. Mint a new key with Read + write access from Account → Personal API keys, or include mcp:write in your OAuth scope= parameter (paired with offline_access if your client refreshes tokens).
2. Permission gate. update_project declares requires: project:update. The MCP layer hides it from tools/list when you lack the permission and re-checks per call (so a stale tools/list cache cannot smuggle the tool past the auth wrapper).
3. Audit log. Every successful or failed call lands a row in org.mcp_audit_logs with userId, projectId, traceId, the tool name, the credential's scope at call time, a SHA-256 hash of the arguments, a one-line summary (e.g. name → New Name), the result, and the wall-clock duration. The args themselves are never stored — only the hash, mirroring the wide log's privacy convention. The Google Ads write tools use the same audit channel.

The core write surface is intentionally tiny (one tool, one mutation: rename the active project) — a demonstrator for the pattern. The richer write surface lives in the Google Ads toolsets, built on the same audit + scope foundation.

#Limits and errors

When you hit the rate limit the server returns a JSON-RPC error with code -32099 and error.data.retryAfter (seconds). Standard MCP clients surface this to the agent; well-behaved agents back off automatically.

#Selecting toolsets

By default a connection boots with the always-on + default toolsets, and the agent expands the surface at runtime with enable_toolset (see Toolsets). If you'd rather pin a fixed surface on the connection — handy for read-only deployments, focused agents, or clients that can't call meta-tools — pass ?toolsets= on the MCP URL or the X-MCP-Toolsets header:

https://www.vtilt.com/api/mcp?toolsets=analytics,persons,google-ads
https://www.vtilt.com/api/mcp?toolsets=all
https://www.vtilt.com/api/mcp?toolsets=default

• A static ?toolsets= / X-MCP-Toolsets value overrides the session-enabled set for that connection (GitHub-style). The always-on meta + context toolsets are always included.
• all exposes every toolset (the full 58-tool surface); default is the boot set (context + analytics + query + docs).
• Valid ids: analytics, persons, recordings, campaign, event-destinations, intelligence, project, query, docs, google-ads, google-ads-shortcuts (plus all / default). Unknown ids are silently ignored.

You can still narrow to individual tools with ?tools= (union semantics — a named tool surfaces even if its toolset is off):

https://www.vtilt.com/api/mcp?tools=get_kpis,list_recent_events

#Next steps

Guides

• Authentication — personal API keys, headers, troubleshooting.
• OAuth — browser sign-in flow for Claude, ChatGPT, Cursor, VS Code, …
• Agent skills (prompts) — /vtilt:… slash commands bundled with the server.
• AI intelligence — AI memory tables, :embed('text'), query_ai_memory, get_person_memory.

Client setup

• Cursor · Claude Desktop · VS Code · Codex

SDK

• Identify & alias — make sure your dashboard data has high-quality persons before asking the agent to reason about them.