VecViz Documentation

Connecting to VecViz

VecViz exposes its model as an MCP server, so any MCP-capable agent can query it directly. There are two ways in.

Either way you need a VecViz API key first.

Get an API Key

• Free trial Ten tickers (AAPL, GLD, JPM, MRK, MSFT, SPY, TLT, TSLA, WMT, XOM), one click, no card, at agents-vecviz.fly.dev/try
• Full access The whole 788-ticker universe, $39 per month, cancel anytime, at vecviz.com/signup

Your key starts with vv_. Treat it the way you would any credential.

Direct Connection

The endpoint is https://agents-vecviz.fly.dev/mcp/, authenticated with your key as a bearer token.

Claude Code

claude mcp add --transport http vecviz "https://agents-vecviz.fly.dev/mcp/" \
  --header "Authorization: Bearer vv_your_key_here"

Add --scope user to make it available across all your projects rather than just the current one.

Gemini CLI and Grok CLI

Same shape, different binary:

gemini mcp add --transport http vecviz "https://agents-vecviz.fly.dev/mcp/" \
  --header "Authorization: Bearer vv_your_key_here"

grok mcp add --transport http vecviz "https://agents-vecviz.fly.dev/mcp/" \
  --header "Authorization: Bearer vv_your_key_here"

The name after add is yours to choose; vecviz is what the tools will be listed under.

Cursor, VS Code, Windsurf and Other Config-File Clients

{
  "mcpServers": {
    "vecviz": {
      "type": "http",
      "url": "https://agents-vecviz.fly.dev/mcp/",
      "headers": {
        "Authorization": "Bearer vv_your_key_here"
      }
    }
  }
}

The file location differs by client. Cursor uses ~/.cursor/mcp.json; VS Code and Windsurf have their own paths. Restart the client after editing.

claude.ai, Claude Desktop and Claude Mobile

The chat apps can take a request header in a custom connector, but in practice the Smithery route runs more reliably: OAuth is the path those clients are built around, and the connection survives session and device changes without re-entering anything. Use the Smithery route below. The direct configuration is documented there too, if you would rather keep your key out of a third party.

Just Ask Your Agent

Most coding agents can wire this up themselves. Paste this:

Connect to the VecViz MCP server at https://agents-vecviz.fly.dev/mcp/ using bearer authentication with the API key vv_your_key_here, then call vecviz_catalog to confirm the connection.

Connecting Through Smithery

This is the recommended route for the chat apps: claude.ai, Claude Desktop, Claude mobile and ChatGPT. It takes a few more steps than the direct route because you are provisioning your own proxy endpoint rather than using a shared one, but once it is set up the connection is stable across sessions and devices.

1. Create a Smithery account at smithery.ai. Note the namespace it gives you. It is usually your username, and it becomes part of your connection URL.
2. Open the VecViz listing at smithery.ai/servers/vecviz/vecviz.
3. Click “Add to toolbox” and pick the namespace you want the connection to live under.
4. Click “Set up” on the VecViz entry that appears in your Toolbox, and paste in your vv_ key. The connection stays inactive until you do this.
5. Click “Install” and choose your client from the list.

claude.ai, Claude Desktop and Claude Mobile

Smithery gives you a URL of the form https://mcp.smithery.ai/your-namespace. In Claude, go to Settings > Connectors, click Add custom connector, and paste it in. Claude will run the OAuth handshake with Smithery once; after that the connector is available in every conversation, on desktop and mobile alike, and your VecViz key never leaves Smithery.

Connecting Claude directly instead, without Smithery

Claude’s custom connectors will accept a request header, so you can point one straight at VecViz. Open Advanced settings when adding the connector and set it up as below. It works, but expect to redo it if things get flaky; the Smithery route above is the one we recommend for these clients.

Name	vecviz
URL	https://agents-vecviz.fly.dev/mcp/
Authentication	None
Request header	authorization = Bearer followed by your full key
Transport	Streamable HTTP

Set Authentication to None, not to a header-based auth type: choosing an authentication method sends Claude looking for an OAuth endpoint that VecViz does not publish, and the connection fails before your header is ever sent. Include the space after Bearer and paste the whole key, vv_ prefix included. Connectors added mid-conversation may not appear until you start a new chat.

Both /mcp/ and /mcp reach the server. If you already added a VecViz connector under the other form, remove it before adding this one: clients treat the two URLs as separate entries and adding the second under the same name fails as a duplicate.

ChatGPT

ChatGPT connects to MCP servers only through OAuth. VecViz does not offer OAuth; it authenticates with an API key. Smithery is the bridge: it speaks OAuth to ChatGPT on one side and holds your VecViz key on the other, so ChatGPT signs in to Smithery and Smithery signs in to VecViz. The credential chain runs like this.

To set it up, complete the five Smithery steps above, then in ChatGPT open Settings > Connectors (under Apps & Connectors on some plans), choose Create or Add custom connector, and give it your namespace URL of the form https://mcp.smithery.ai/your-namespace. Leave the authentication method as OAuth. ChatGPT will send you to Smithery to authorise the connection once; after that, VecViz tools appear in the conversation’s tool list and the metering lands on your VecViz account, not on ChatGPT’s.

The screens below walk through it. Click any image to expand it.

← Previous Close Next →

Everything Else

Smithery’s install dialog covers Claude Code, Codex, Cursor, VS Code, Gemini CLI, LM Studio, Cline, Zed, OpenCode, Antigravity, Cherry Studio, ChatWise, Roo Code, Amazon Q, Dust, LibreChat, Kiro and others. Pick yours and follow the command or config it produces.

For a client not on the list, the “Advanced” panel gives you raw JSON. That config authenticates to Smithery with a Smithery API key, not your VecViz key. Your VecViz key is already stored on the connection itself from step 4.

Two Things Worth Knowing

Your namespace URL is personal. It is bound to your toolbox and your stored key, so anyone you shared it with would be spending your quota. It is not a link to publish or pass around.

Your toolbox bundles every server you have added to that namespace behind one URL, so if you add others alongside VecViz, they all arrive together and tool names may come back prefixed with the connection ID.

Confirming It Works

Ask your agent to call vecviz_catalog. It is free and returns the coverage list, which tells you the transport is up.

Then ask for vecviz_read on SPY. That one is metered, so a clean response confirms your key made it through and is being counted against the right account. If vecviz_catalog succeeds but vecviz_read fails, the connection is fine and the problem is the key.

From there, methodology explains what any number means, and model_review shows the published track record. Both are free.

Where to Start

vecviz_read on a single ticker is self-sufficient: target price, channels, VecEvents, V-Score and which price-probability bands exist. Most sessions start there and follow the thread into vecevent_matrix to see why the target is what it is, or price_likelihood to ask whether a given price is reachable.