MCP Server

The VH3 AI MCP server exposes the full intelligence layer as Model Context Protocol tools. Any MCP-compatible client, Claude Desktop, Cursor, a custom agent, or your own toolchain, can connect directly without building middleware. Once connected, the client gets the same tools used by the Connie assistant: investigate, aggregate_jobs, jobs_feed, run_sentinels, reports_generate, search_outcomes, and more, with all credentials and routing handled server-side via JWT authentication.

Server details

Property	Value
SSE endpoint	`https://api.vh3connect.io/x2/mcp/UZkEeuG7/mcp/sse`
Transport	SSE (Server-Sent Events) via `mcp-remote` proxy
Auth	Bearer JWT token in `Authorization` header (obtained from `auth/mcp-token`)
Protocol version	MCP 2025-06-18

Prerequisites

Claude Desktop and Cursor connect to remote MCP servers via a lightweight proxy called mcp-remote. It runs automatically through npx, which ships with Node.js.

Install Node.js (if not already installed)

Download the LTS installer for your platform from nodejs.org:

macOS: Download the .pkg installer from nodejs.org, open it, and click through the wizard. No terminal required.
Windows: Download the .msi installer. Make sure “Add to PATH” is checked during installation (this is the default).

After installing, verify by opening a terminal (macOS: Terminal.app, Windows: Command Prompt) and running:

node --version
npx --version

Both should return a version number (e.g. v22.x.x). If npx is not recognised, Node.js is either not installed or not in your system PATH — see Troubleshooting below.

Confirm your IT policy allows outbound HTTPS

The MCP proxy makes outbound HTTPS connections to api.vh3connect.io and registry.npmjs.org (to fetch mcp-remote on first use). If your organisation uses a firewall or proxy, ask your IT team to allowlist these domains.

Why Node.js? Claude Desktop only supports local process (stdio) MCP servers in its config file. It cannot connect to remote HTTP/SSE endpoints directly. The mcp-remote proxy bridges the gap — Claude Desktop launches it as a local process, and it handles the network connection to VH3. This is the standard pattern recommended by the MCP specification.

Get your MCP token

Before connecting any client, you need a long-lived MCP token (valid for 90 days).

Call the login endpoint with your email and password to obtain a standard session token:

curl -X POST https://api.vh3connect.io/api:lBQnyyZL/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com", "password": "your-password"}'

Copy the authToken from the response.

Exchange it for an MCP token

Call the auth/mcp-token endpoint using your session token:

curl -X POST https://api.vh3connect.io/api:lBQnyyZL/auth/mcp-token \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

The response contains authToken (your 90-day MCP token) and expires_in: 7776000.

Store the token securely

Save the MCP token in an environment variable. Never commit it to source control.

export VH3_MCP_TOKEN="eyJhbGci..."

Quick start: Claude Desktop

Claude Desktop connects to the VH3 MCP server via SSE using the mcp-remote proxy. Requires Node.js 18+.

Open your Claude Desktop config file

The config file location depends on your platform:

Platform	Path
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

You can also open it from Claude Desktop: Settings → Developer → Edit Config.Create the file if it does not exist.

Add the VH3 server

macOS:

claude_desktop_config.json

{
  "mcpServers": {
    "vh3-ai": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.vh3connect.io/x2/mcp/UZkEeuG7/mcp/sse",
        "--header",
        "Authorization:${VH3_MCP_TOKEN}"
      ],
      "env": {
        "VH3_MCP_TOKEN": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}

Windows:

claude_desktop_config.json

{
  "mcpServers": {
    "vh3-ai": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "mcp-remote",
        "https://api.vh3connect.io/x2/mcp/UZkEeuG7/mcp/sse",
        "--header",
        "Authorization:${VH3_MCP_TOKEN}"
      ],
      "env": {
        "VH3_MCP_TOKEN": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}

Replace YOUR_MCP_TOKEN with the token from Get your MCP token.

Restart Claude Desktop

Quit fully (Cmd+Q on macOS, File → Quit on Windows — closing the window is not enough) and reopen. You should see a hammer icon in the chat input. Click it to confirm the VH3 tools are listed.

Test with a query

Try: “How many jobs did we complete last week, broken down by engineer?”Claude will call aggregate_jobs and return a cited answer.

Windows users: You must use "command": "cmd" with "/c" as the first arg. Claude Desktop spawns the command directly without a shell, so npx alone will fail with spawn npx ENOENT. Wrapping it in cmd /c ensures Windows resolves npx via the system PATH.

The auth token is placed in the env block rather than inline in args. This is the recommended pattern — mcp-remote can misparse header values containing spaces when they appear directly in the args array on Windows.

Quick start: Cursor

Go to Cursor Settings → MCP and add a new server, or edit .cursor/mcp.json in your project root. Requires Node.js 18+. macOS:

.cursor/mcp.json

{
  "mcpServers": {
    "vh3-ai": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.vh3connect.io/x2/mcp/UZkEeuG7/mcp/sse",
        "--header",
        "Authorization:${VH3_MCP_TOKEN}"
      ],
      "env": {
        "VH3_MCP_TOKEN": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}

Windows:

.cursor/mcp.json

{
  "mcpServers": {
    "vh3-ai": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "mcp-remote",
        "https://api.vh3connect.io/x2/mcp/UZkEeuG7/mcp/sse",
        "--header",
        "Authorization:${VH3_MCP_TOKEN}"
      ],
      "env": {
        "VH3_MCP_TOKEN": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}

Replace YOUR_MCP_TOKEN with your token. See Get your MCP token.

Prefer environment variables over inline tokens. Set VH3_MCP_TOKEN in your shell profile and reference it from the config, or use Cursor Rules alongside the MCP connection to keep tokens out of config files.

Available tools

Once connected, these tools are available in any MCP-compatible client. No company_id or api_key inputs are needed, credentials are resolved automatically from your JWT.

FSI Intelligence

Tool	Description	Typical latency
`connie_chat`	Conversational AI assistant trained on your company’s data	5–15 s
`investigate`	Deep evidence-backed investigation using graph + vector search	10–17 s
`search_outcomes`	Semantic search over job outcome text	< 2 s
`search_autocomplete`	Fast typeahead across jobs, contacts, engineers, sites	< 1 s
`contacts_feed`	Paginated contact list with free-text search	< 3 s
`contact_detail`	Full contact detail with optional stored summary	< 3 s
`weather_for_job`	Weather conditions for a job’s location and time	< 2 s
`company_snapshot`	Company profile and FSI platform health	< 2 s
`reports_generate`	Operational reports (start_of_day, close_of_business, etc.)	10–17 s
`run_sentinels`	Run sentinel alert rules on demand	3–8 s

Jobs

Tool	Description	Typical latency
`list_jobs`	Paginated job listing with filters (status, type, contact, resource)	< 3 s
`get_job`	Full FSI-enriched job detail with worksheets and graph context	< 3 s
`jobs_feed`	Paginated job feed (alias for list_jobs)	< 3 s
`aggregate_jobs`	KPI metrics with period comparison and group-by dimensions	< 3 s
`get_fsi_job`	FSI-enriched job detail (alias for get_job)	< 3 s

Quotes & Invoices

Tool	Description	Typical latency
`list_quotes`	Paginated quote listing with filters	< 3 s
`get_quote`	Full quote detail with line items	< 2 s
`list_invoices`	Paginated invoice listing with filters	< 3 s
`get_invoice`	Full invoice detail with line items and payment status	< 2 s

investigate, reports_generate, and connie_chat have 10–17s expected latency. Some MCP clients have aggressive timeouts. If you see tool call failures on these endpoints, check your client’s timeout setting and increase it to at least 25 seconds.

Authentication

The MCP server uses JWT Bearer token authentication. Tokens are obtained via the auth/mcp-token endpoint (see Get your MCP token above).

Property	Value
Header	`Authorization: Bearer <token>`
Token lifetime	90 days
Scope	Automatically resolves your user, company, and API credentials

The JWT encodes your user identity. All tool calls are automatically scoped to your company, no company_id or api_key parameters are needed. Cross-tenant access is impossible.

Never commit your MCP token to source control. Use environment variables and reference them from your MCP client configuration.

Troubleshooting

`spawn npx ENOENT` (Windows)

Claude Desktop cannot find npx. Two possible causes:

Node.js is not installed. Install it from nodejs.org and restart Claude Desktop.
Node.js is installed but not in Claude Desktop’s PATH. Use "command": "cmd" with "/c" as the first arg (see Windows config above). Alternatively, use the full path to npx: "command": "C:\\Program Files\\nodejs\\npx.cmd".

`npx is not recognized` (Windows)

Same root cause as above — Node.js is not on the system PATH. Install Node.js using the .msi installer (not the zip), which adds it to PATH automatically. After installing, restart Claude Desktop (or reboot) so it picks up the new PATH.

”Not valid MCP server configuration”

The config JSON is malformed. Common causes:

Trailing comma after the last entry in an object or array.
Two separate JSON objects instead of one (e.g. mcpServers and preferences in separate {} blocks — they must be siblings in a single root object).
Using "url" or "headers" keys — Claude Desktop does not support these. Use the command + mcp-remote pattern shown above.

Paste your config into jsonlint.com to validate the JSON syntax.

Tools don’t appear after restart

Verify you fully quit Claude Desktop (Cmd+Q / File → Quit), not just closed the window.
Check logs: Settings → Developer → Open Logs Folder and look for mcp-remote stderr output.
Verify your token hasn’t expired (90-day lifetime). Re-run the token exchange if needed.
Confirm outbound HTTPS to api.vh3connect.io and registry.npmjs.org is not blocked by a firewall.

Tool calls timeout

investigate, reports_generate, and connie_chat can take 10–17 seconds. Some clients have aggressive timeouts. Increase your client’s tool call timeout to at least 25 seconds.

Using the MCP server from custom agents

For agents built with the Anthropic SDK, OpenAI Agents SDK, or similar frameworks:

import os
import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-5",
    max_tokens=4096,
    mcp_servers=[
        {
            "type": "url",
            "url": "https://api.vh3connect.io/x2/mcp/UZkEeuG7/mcp/sse",
            "name": "vh3-ai-v2",
            "authorization_token": os.environ["VH3_MCP_TOKEN"],
        }
    ],
    messages=[{"role": "user", "content": "What needs attention today?"}],
)

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";

const transport = new SSEClientTransport(
  new URL("https://api.vh3connect.io/x2/mcp/UZkEeuG7/mcp/sse"),
  {
    requestInit: {
      headers: {
        Authorization: `Bearer ${process.env.VH3_MCP_TOKEN!}`,
      },
    },
  }
);

const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);

const tools = await client.listTools();
console.log(tools); // lists all 19 VH3 tools

Tool selection guide for agents

When your agent receives a free-form question and needs to decide which tool to call:

Question pattern	Tool
”why / root cause / what’s causing / investigate”	`investigate`
”how many / rate / trend / top / compare / period over period”	`aggregate_jobs`
”show me / list / find / get jobs”	`list_jobs` or `jobs_feed`
”what needs attention / alerts / sentinels”	`run_sentinels`
”generate report / briefing / debrief / weekly summary”	`reports_generate`
”similar to / fault like / what else looks like”	`search_outcomes`
”find customer / contact / site”	`contacts_feed` or `search_autocomplete`
”quotes / pricing / quotations”	`list_quotes` or `get_quote`
”invoices / billing / payments”	`list_invoices` or `get_invoice`
Ambiguous / unclear	`aggregate_jobs` first, then offer `investigate`

For a full system prompt you can paste directly into your agent, see the Claude.ai Projects and n8n Agent Prompts kits, both include routing logic optimised for agent use.

Pairing with AGENTS.md

If you’re using the MCP server inside a Cursor or Claude Code session, pair it with the AGENTS.md file in your project root. The MCP server handles execution; AGENTS.md handles routing logic, field name correctness, and the rules around what IDs to expose to users.

MCP Server (this page)

Handles execution, connects the client to the actual API, manages auth, returns real data.

AGENTS.md

Handles reasoning, tells the agent which tool to call, which parameters to pass, and how to present results.

​MCP Server

​Server details

​Prerequisites

​Get your MCP token

​Quick start: Claude Desktop

​Quick start: Cursor

​Available tools

​FSI Intelligence

​Jobs

​Quotes & Invoices

​Authentication

​Troubleshooting

​spawn npx ENOENT (Windows)

​npx is not recognized (Windows)

​”Not valid MCP server configuration”

​Tools don’t appear after restart

​Tool calls timeout

​Further reading

​Using the MCP server from custom agents

​Tool selection guide for agents

​Pairing with AGENTS.md

MCP Server (this page)

AGENTS.md

MCP Server

Server details

Prerequisites

Get your MCP token

Quick start: Claude Desktop

Quick start: Cursor

Available tools

FSI Intelligence

Jobs

Quotes & Invoices

Authentication

Troubleshooting

`spawn npx ENOENT` (Windows)

`npx is not recognized` (Windows)

”Not valid MCP server configuration”

Tools don’t appear after restart

Tool calls timeout

Further reading

Using the MCP server from custom agents

Tool selection guide for agents

Pairing with AGENTS.md