Cursor

Cursor ships first-class support for remote MCP servers — no bridge process required. Once configured, every Cursor chat (and Cursor's coding agent) can call vTilt tools while keeping the same vtu_ key for the lifetime of the connection.

#1. Open Cursor's MCP settings

• Cursor desktop → Settings (gear icon, top-right of the chat) → Model Context Protocol.
• Or open the file directly: ~/.cursor/mcp.json (macOS / Linux) / %USERPROFILE%\.cursor\mcp.json (Windows).

#2. Add the vTilt server

Add this entry under mcpServers:

{
  "mcpServers": {
    "vtilt": {
      "url": "https://www.vtilt.com/api/mcp",
      "headers": {
        "Authorization": "Bearer vtu_YOUR_SECRET"
      }
    }
  }
}

Save and reload Cursor (the chat panel auto-reconnects).

#3. Pin a project (multi-project users only)

If your account has access to more than one project, add a header so the server doesn't have to ask:

{
  "mcpServers": {
    "vtilt": {
      "url": "https://www.vtilt.com/api/mcp",
      "headers": {
        "Authorization": "Bearer vtu_YOUR_SECRET",
        "x-vtilt-project-id": "YOUR_PROJECT_ID"
      }
    }
  }
}

You can find the project id at Project settings → General in the dashboard.

If you'd rather pick the project conversationally, omit x-vtilt-project-id and ask the agent: "List my projects, then switch me to the Marketing site one." Cursor will call list_projects to see the catalog, then switch_project (accepts the project's display name directly — UUID not required), and remember the pin for 30 days.

#Parallel chats with one key (x-vtilt-mcp-session-id)

If several Cursor chats (or agents) share the same vtu_ secret, each switch_project call would normally overwrite the same Redis pin. Add a stable UUID per MCP server entry so each connection gets its own pin namespace:

{
  "mcpServers": {
    "vtilt": {
      "url": "https://www.vtilt.com/api/mcp",
      "headers": {
        "Authorization": "Bearer vtu_YOUR_SECRET",
        "x-vtilt-mcp-session-id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
      }
    }
  }
}

Generate a fresh UUID for every duplicate entry (for example vtilt-marketing-chat vs vtilt-product-chat). Invalid or malformed values are ignored — behaviour falls back to the shared default pin.

#4. Verify the connection

In a new Cursor chat, ask:

List the available vTilt tools.

Cursor calls tools/list and you should see the boot toolsets: the meta trio (list_toolsets, get_toolset, enable_toolset), the orientation set get_guide / get_context / get_data_model / list_projects (plus switch_project when you have more than one accessible project and did not set x-vtilt-project-id), the analytics set (get_kpis, get_attribution, list_recent_events, list_event_types), the VQL trio (run_query, validate_query, get_query_schema), and search_docs (see Supported tools). Feature toolsets — session recordings, AI memory, and Google Ads — also appear here automatically when your pinned project has that feature connected. The remaining domains (persons, campaigns, event destinations) are not in this list until the agent enables their toolset — ask "what toolsets are available?" to make Cursor call list_toolsets, then enable_toolset.

If Cursor reports a connection error:

• Check the secret was copied in full — they're long.
• Check the header line ends with the secret and not the project token (vt_); see Authentication for the difference.
• Try a curl health check from the Authentication page.

#5. Try a real prompt

Compare last week's visits to the previous week. Show the
top 5 sources for each week side by side.

Cursor will call get_kpis (twice, once per week) and synthesise the comparison into the chat. The same prompt with list_recent_events works directly; list_recordings is available the moment session replay is enabled on the project (the recordings toolset auto-lists) — Cursor figures out which tool to use.

Naming a project in the prompt also works:

Switch to the Product app project and show me last week's KPIs.

Cursor calls list_projects (to map "Product app" → UUID), switch_project with the resolved id, and then get_kpis. The pin sticks for the rest of the conversation, so subsequent prompts ("show me churn this quarter") stay on the same project until you ask to switch again.

#6. Pin a fixed toolset (optional)

By default Cursor sees the boot toolsets and enables more on demand. If you want to lock the surface — e.g. only analytics tools while writing a marketing report — add a ?toolsets= (or ?tools=) query parameter to the URL. See Selecting toolsets for the full list of ids (all, default, persons, google-ads, …).

{
  "mcpServers": {
    "vtilt-analytics-only": {
      "url": "https://www.vtilt.com/api/mcp?toolsets=analytics",
      "headers": {
        "Authorization": "Bearer vtu_YOUR_SECRET",
        "x-vtilt-project-id": "YOUR_PROJECT_ID"
      }
    }
  }
}

You can register the same key under multiple server names with different filters and pick the right one per conversation.

#7. Multiple projects, multiple entries

To make several projects always-on (rather than switch_project-on-demand), register one entry per project:

{
  "mcpServers": {
    "vtilt-marketing": {
      "url": "https://www.vtilt.com/api/mcp",
      "headers": {
        "Authorization": "Bearer vtu_YOUR_SECRET",
        "x-vtilt-project-id": "PROJECT_ID_MARKETING"
      }
    },
    "vtilt-product": {
      "url": "https://www.vtilt.com/api/mcp",
      "headers": {
        "Authorization": "Bearer vtu_YOUR_SECRET",
        "x-vtilt-project-id": "PROJECT_ID_PRODUCT"
      }
    }
  }
}

Cursor exposes them as vtilt-marketing and vtilt-product separately.

#Troubleshooting

• "Unauthorized" — the bearer token is missing, malformed, revoked, or expired. Check the error table.
• "Forbidden — project_not_accessible" — x-vtilt-project-id points at a project you don't have access to. Remove the header to fall back to switch_project, or use a project id from your dashboard.
• "Rate limit exceeded" — you've made more than 60 requests in the last minute on this key. Cursor surfaces retryAfter to the agent; well-behaved agents back off automatically.
• No tools shown — the connection is up but tools/list returned an empty list. This usually means the key has scopedProjectIds allowlisting projects you no longer access. Create a fresh key.

#Next steps

• Authentication — full key lifecycle and error reference.
• MCP server overview — the seven phase-1 tools and what they do.