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 projects-list 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 orientation pair vtilt-guide / context-get, plus kpis-get, persons-list, persons-get, events-recent, recordings-list, project-get, project-config-get, projects-list, the VQL trio (query-run, query-validate, schema-get), and usually switch-project when you have more than one accessible project and did not set x-vtilt-project-id (see Supported tools). vtilt-guide, context-get, and projects-list are always present — vtilt-guide teaches Cursor the data model, and projects-list is the discovery tool it uses when you mention a project by name. Permission-gated tools (e.g. recordings-list for users without replay:read, or when session replay is disabled on the project) are silently omitted.

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 kpis-get (twice, once per week) and synthesise the comparison into the chat. The same prompt with recordings-list or events-recent works — 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 projects-list (to map "Product app" → UUID), switch-project with the resolved id, and then kpis-get. 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. Filter the tool list (optional)

If you want to keep the agent focused — e.g. only analytics tools while writing a marketing report — add a ?features= or ?tools= query parameter to the URL. Both filters apply with union semantics.

{
  "mcpServers": {
    "vtilt-analytics-only": {
      "url": "https://www.vtilt.com/api/mcp?features=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.