MCP + CLI Setup

Connect sessionvision to your AI coding assistant or terminal in under a minute. Once connected, you can query your analytics data, explore schema, and run analyses using natural language.

Prerequisites

A sessionvision account with at least one project
Claude Code, Cursor, or any MCP-compatible client installed

1. Add the MCP Server

Run this command to register sessionvision as an MCP server:

claude mcp add --transport http sessionvision https://app.sessionvision.com/api/v1/mcp

For Cursor or other MCP clients, add this to your MCP config file:

{
  "mcpServers": {
    "sessionvision": {
      "transport": "http",
      "url": "https://app.sessionvision.com/api/v1/mcp"
    }
  }
}

2. Authenticate

On first use, an OAuth 2.0 PKCE authorization flow opens in your browser. Sign in with your sessionvision account and authorize the connection. Tokens are stored locally and refreshed automatically — you only need to do this once.

3. Verify the Connection

Ask your AI assistant a question about your data to confirm everything is working:

"What are my top 10 events by volume?"
"Show me the database schema"
"How many unique users visited /pricing this week?"

You should see the assistant call sessionvision tools like get_event_definitions or query and return real data from your project.

Available Tools

Once connected, your AI assistant has access to these tools:

Tool	Description
`query`	`Execute read-only SQL against your analytics database`
`get_schema`	`Get database schema, tables, and columns`
`list_events`	`List recent events with filters`
`get_event_definitions`	`Get all unique event names and counts`
`get_property_definitions`	`Get all property names used in events`

The sessionvision://schema resource is also available for clients that support MCP resources.

Example Workflows

Investigate a Bug

"List all events from user_123 in the last 24 hours"
"Show me the session recording for session abc-def"
"What errors occurred on /checkout today?"

Product Analysis

"What's the conversion rate from signup to first purchase this month?"
"Which pages have the highest bounce rate?"
"Break down pageviews by browser for the last 7 days"

Schema Exploration

"What tables are available?"
"Show me all properties on $click events"
"What event definitions exist in my project?"

Scopes

The OAuth flow requests the mcp:analytics:read bundle scope, which includes read access to all analytics data. Individual scopes are available for more granular control:

Scope	Description
`mcp:query:read`	`Execute read-only queries`
`mcp:events:read`	`List and retrieve events`
`mcp:persons:read`	`List and retrieve persons`
`mcp:sessions:read`	`List and retrieve sessions`
`mcp:insights:read`	`Run trends and funnel analyses`
`mcp:schema:read`	`Read database schema`
`mcp:analytics:read`	`Bundle scope (all read operations)`

Troubleshooting

Auth flow doesn't open

Make sure your MCP client supports HTTP transport. Some older clients only support stdio. Check that the URL is exactly https://app.sessionvision.com/api/v1/mcp.

Tools return empty results

Verify that you've sent events to your project. The MCP server only returns data from the project associated with your authenticated account.

Token expired

Tokens refresh automatically. If you're prompted to re-authenticate, remove and re-add the MCP server:

claude mcp remove sessionvision
claude mcp add --transport http sessionvision https://app.sessionvision.com/api/v1/mcp