> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vh3.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect any MCP-compatible AI client, Claude Desktop, Cursor, custom agents, directly to the VH3 intelligence layer

# MCP Server

The VH3 AI MCP server exposes the full intelligence layer as [Model Context Protocol](https://modelcontextprotocol.io) 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`](https://www.npmjs.com/package/mcp-remote). It runs automatically through `npx`, which ships with Node.js.

<Steps>
  <Step title="Install Node.js (if not already installed)">
    Download the **LTS** installer for your platform from [nodejs.org](https://nodejs.org/en/download):

    * **macOS:** Download the `.pkg` installer from [nodejs.org](https://nodejs.org/en/download), 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:

    ```bash theme={null}
    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](#troubleshooting) below.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Info>
  **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](https://modelcontextprotocol.io/quickstart/user) recommended by the MCP specification.
</Info>

## Get your MCP token

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

<Steps>
  <Step title="Log in to get a session JWT">
    Call the login endpoint with your email and password to obtain a standard session token:

    ```bash theme={null}
    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.
  </Step>

  <Step title="Exchange it for an MCP token">
    Call the `auth/mcp-token` endpoint using your session token:

    ```bash theme={null}
    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`.
  </Step>

  <Step title="Store the token securely">
    Save the MCP token in an environment variable. Never commit it to source control.

    ```bash theme={null}
    export VH3_MCP_TOKEN="eyJhbGci..."
    ```
  </Step>
</Steps>

## Quick start: Claude Desktop

Claude Desktop connects to the VH3 MCP server via SSE using the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) proxy. Requires [Node.js 18+](#prerequisites).

<Steps>
  <Step title="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.
  </Step>

  <Step title="Add the VH3 server">
    **macOS:**

    ```json claude_desktop_config.json theme={null}
    {
      "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:**

    ```json claude_desktop_config.json theme={null}
    {
      "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](#get-your-mcp-token).
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  **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.
</Warning>

<Note>
  The auth token is placed in the `env` block rather than inline in `args`. This is the [recommended pattern](https://www.npmjs.com/package/mcp-remote) — `mcp-remote` can misparse header values containing spaces when they appear directly in the args array on Windows.
</Note>

## 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+](#prerequisites).

**macOS:**

```json .cursor/mcp.json theme={null}
{
  "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:**

```json .cursor/mcp.json theme={null}
{
  "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](#get-your-mcp-token).

<Note>
  Prefer environment variables over inline tokens. Set `VH3_MCP_TOKEN` in your shell profile and reference it from the config, or use [Cursor Rules](/agent-kits/cursor-rules) alongside the MCP connection to keep tokens out of config files.
</Note>

## 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          |

<Warning>
  `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.
</Warning>

## Authentication

The MCP server uses JWT Bearer token authentication. Tokens are obtained via the `auth/mcp-token` endpoint (see [Get your MCP token](#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.

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

## Troubleshooting

### `spawn npx ENOENT` (Windows)

Claude Desktop cannot find `npx`. Two possible causes:

1. **Node.js is not installed.** Install it from [nodejs.org](https://nodejs.org/en/download) and restart Claude Desktop.
2. **Node.js is installed but not in Claude Desktop's PATH.** Use `"command": "cmd"` with `"/c"` as the first arg (see [Windows config above](#quick-start-claude-desktop)). 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](https://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](#get-your-mcp-token) 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.

### Further reading

* [MCP Specification](https://modelcontextprotocol.io) — the protocol standard
* [MCP Debugging Guide](https://modelcontextprotocol.io/docs/tools/debugging) — official troubleshooting
* [`mcp-remote` on npm](https://www.npmjs.com/package/mcp-remote) — the SSE proxy package
* [Claude Desktop MCP Quickstart](https://modelcontextprotocol.io/quickstart/user) — Anthropic's setup guide

## Using the MCP server from custom agents

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

<CodeGroup>
  ```python Python (Anthropic SDK) theme={null}
  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?"}],
  )
  ```

  ```typescript TypeScript (SSE transport) theme={null}
  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
  ```
</CodeGroup>

## 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](/agent-kits/claude-projects) and [n8n Agent Prompts](/agent-kits/n8n-agents) 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](/agent-kits/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.

<CardGroup cols={2}>
  <Card title="MCP Server (this page)" icon="plug">
    Handles *execution*, connects the client to the actual API, manages auth, returns real data.
  </Card>

  <Card title="AGENTS.md" icon="robot">
    Handles *reasoning*, tells the agent which tool to call, which parameters to pass, and how to present results.
  </Card>
</CardGroup>