Connect AI assistants with the Vision MCP Server

Connect Claude Desktop, Cursor, Antigravity, and autonomous agents to live business observability metrics and unit economics via the Model Context Protocol.

The Vision Model Context Protocol (MCP) Server enables AI assistants, IDE copilots, and autonomous agents to query your live business health, customer unit economics, LLM inference latency, and experiment metrics in real time.

Instead of switching back and forth between dashboards, your AI assistant can inspect customer margins, investigate prompt costs, check A/B test conversion rates, and audit error spikes directly from your conversational workflow.


What is MCP?

The Model Context Protocol (MCP) is an open standard that allows LLM applications to securely interact with external tools and data sources.

Vision provides an official @vision/mcp package that implements the MCP specification over standard input/output (stdio), making it plug-and-play with compatible AI clients including:

  • Claude Desktop
  • Cursor IDE
  • Google Antigravity
  • Windsurf
  • Custom Agent Frameworks (LangChain, LlamaIndex, MCP TypeScript / Python SDKs)

Prerequisites

Before configuring your client, make sure you have:

  1. Node.js (v18 or newer installed on your machine).
  2. Your Vision Project ID (found in your dashboard URL: /[organizationId]/[projectId], or under Settings > Project Details).
  3. A Vision API Key (generated in Settings > API Keys).

Client Setup

1. Claude Desktop

To connect Claude Desktop to your Vision project:

  1. Open your Claude Desktop configuration file:
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
    • Linux: ~/.config/Claude/claude_desktop_config.json
  2. Add the sigma server under mcpServers:
{
  "mcpServers": {
    "vision": {
      "command": "npx",
      "args": ["-y", "@vision/mcp"],
      "env": {
        "VISION_API_KEY": "sg_live_your_api_token",
        "VISION_PROJECT_ID": "your-project-id"
      }
    }
  }
}
  1. Restart Claude Desktop. You will see a hammer icon indicating that Vision tools are available.

2. Cursor IDE

You can configure Cursor either per-workspace or globally.

Create a .cursor/mcp.json file in the root of your project:

{
  "mcpServers": {
    "vision-observability": {
      "command": "npx",
      "args": ["-y", "@vision/mcp"],
      "env": {
        "VISION_API_KEY": "sg_live_your_api_token",
        "VISION_PROJECT_ID": "your-project-id"
      }
    }
  }
}

Global Configuration

  1. In Cursor, open Settings (Cmd+, or Ctrl+,).
  2. Search for MCP or navigate to Features > MCP.
  3. Click Add New MCP Server:
    • Name: vision
    • Type: command
    • Command: npx -y @vision/mcp
    • Add environment variables VISION_API_KEY and VISION_PROJECT_ID.

3. Google Antigravity & Agentic IDEs

In Antigravity or any agent environment supporting MCP stdio servers, add the configuration to your workspace .antigravity/mcp.json or global configuration:

{
  "mcpServers": {
    "vision": {
      "command": "npx",
      "args": ["-y", "@vision/mcp"],
      "env": {
        "VISION_API_KEY": "sg_live_your_api_token",
        "VISION_PROJECT_ID": "your-project-id"
      }
    }
  }
}

4. Windsurf IDE

Add the server definition to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "vision": {
      "command": "npx",
      "args": ["-y", "@vision/mcp"],
      "env": {
        "VISION_API_KEY": "sg_live_your_api_token",
        "VISION_PROJECT_ID": "your-project-id"
      }
    }
  }
}

5. Custom Node.js or Python Agents

You can also spawn the server inside custom orchestration frameworks using the official @modelcontextprotocol/sdk:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "npx",
  args: ["-y", "@vision/mcp"],
  env: {
    ...process.env,
    VISION_API_KEY: "sg_live_your_api_token",
    VISION_PROJECT_ID: "your-project-id",
  },
});

const client = new Client(
  { name: "custom-agent", version: "1.0.0" },
  { capabilities: {} }
);

await client.connect(transport);

// List available tools
const tools = await client.listTools();
console.log("Connected Vision tools:", tools.tools.map((t) => t.name));

Available MCP Tools

Once connected, your AI assistant has access to the following 6 observability tools:

Tool NameParametersDescription
vision_get_business_scorecardprojectId (string)Returns top-level MRR, total AI compute spend, blended gross margin, active user count, and cost-to-serve (CTS).
vision_get_unit_economicsprojectId (string), limit (number, optional)Returns customer unit economics rankings, identifying top margin contributors and loss-making accounts.
vision_get_user_financialsprojectId (string), userId (string)Audits a specific customer account: subscription tier, paid revenue, token usage, compute cost, and net margin.
vision_get_llm_observabilityprojectId (string)Returns streaming Time-To-First-Token (TTFT), p95 response time, model breakdown, token volumes, and error rates.
vision_query_reliabilityprojectId (string)Returns active runtime errors, crash rates, affected customer volume, and performance degradation.
vision_list_experimentsprojectId (string)Returns running A/B tests and feature flags with real-time conversion rates and sample counts from Tinybird.

Example Natural Language Queries

Try asking your AI assistant questions like:

Executive & Financial Health

"What is our blended gross margin this month, and what percentage of revenue was consumed by LLM inference costs?"

"Which customer accounts have negative gross margins where model inference exceeds their subscription revenue?"

Individual Customer Audits

"Inspect account usr_enterprise_01. How much revenue did they generate vs how much did their tokens cost us?"

Model & Infrastructure Performance

"What is our p95 streaming TTFT latency across models over the last 24 hours? Are we seeing any latency regressions on GPT-4o?"

"Do we have any prompt templates with unusually high error rates or sudden cost spikes today?"

Experiments & Growth

"Are any running A/B tests showing statistically significant conversion gains?"


Environment Variables Reference

VariableDescriptionRequiredDefault
VISION_PROJECT_IDThe target project ID in VisionYes (or passed in tool args)-
VISION_API_KEYYour Vision API authentication tokenYes (for live cloud queries)-
VISION_API_URLBase URL for Vision API endpointsNoNEXT_PUBLIC_API_URL

Troubleshooting

Tool Calls Fail with "projectId is required"

Ensure you provided VISION_PROJECT_ID in the env object of your client configuration, or specify it explicitly when prompting the model.

Permission Denied / 401 Unauthorized

Check that your VISION_API_KEY is valid and active in Settings > API Keys with read permissions for the project.

Testing Locally

You can test the MCP server directly in your terminal using the MCP Inspector:

npx -y @modelcontextprotocol/inspector npx -y @vision/mcp