Skip to main content

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

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, sentinels_run, reports_generate, search_outcomes, and more — with all credentials and routing handled server-side.

​
Server details

PropertyValue
Server URLhttps://api.vh3connect.io/api:kP8T1CK7/mcp
TransportHTTP (Streamable HTTP, MCP spec 2025-03-26)
Authcompany_id + api_key passed as headers (see below)
Protocol versionMCP 2025-03-26

​
Quick start — Claude Desktop

1

Open your Claude Desktop config

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.jsonOn Windows: %APPDATA%\Claude\claude_desktop_config.jsonCreate the file if it does not exist.
2

Add the VH3 server

claude_desktop_config.json
{
  "mcpServers": {
    "vh3-ai": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.vh3connect.io/api:kP8T1CK7/mcp"],
      "env": {
        "VH3_COMPANY_ID": "your-company-id",
        "VH3_API_KEY": "your-api-key"
      }
    }
  }
}
Replace your-company-id and your-api-key with your real credentials. See Authentication if you don’t have them yet.
3

Restart Claude Desktop

Quit and reopen Claude Desktop. You should see a hammer icon (🔨) in the chat input — click it to confirm the VH3 tools are listed.
4

Test with a query

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

​
Quick start — Cursor

Add the server to your Cursor MCP configuration. Go to Cursor Settings → MCP and add:
Cursor MCP config
{
  "vh3-ai": {
    "url": "https://api.vh3connect.io/api:kP8T1CK7/mcp",
    "headers": {
      "x-vh3-company-id": "your-company-id",
      "x-vh3-api-key": "your-api-key"
    }
  }
}
For Cursor, prefer using environment variables rather than inline credentials. Set VH3_COMPANY_ID and VH3_API_KEY in your shell profile, then reference them in the header values with $VH3_COMPANY_ID syntax if your Cursor version supports it — or use Cursor Rules alongside the MCP connection to keep credentials out of config files.

​
Available tools

Once connected, these tools are available in any MCP-compatible client:
ToolDescriptionTypical latency
investigateHybrid diagnostic — root cause analysis, cited evidence, ranked recommendations10–17 s
aggregate_jobsCompute metrics over jobs with period shorthand and comparison< 3 s
jobs_feedFetch individual job records with filters< 3 s
sentinels_runRun early-warning sentinels, return only triggered alerts3–8 s
reports_generateGenerate structured operational reports (start_of_day, close_of_business, etc.)10–17 s
search_outcomesSemantic search over outcome text — find similar fault descriptions< 2 s
search_personsLook up engineers, contacts, or customers by name, email, or phone< 1 s
weather_for_jobGet weather context for a specific job’s time and location< 2 s
weather_for_siteGet weather context for a site over a date range< 2 s
investigate and reports_generate have 10–17s expected latency when includeNarrative: true. 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 reads credentials from request headers. Two header names are accepted:
HeaderValue
x-vh3-company-idYour company ID
x-vh3-api-keyYour API key
Credentials are scoped per-request — each tool call is independently authenticated. There is no session token to manage.
Never commit your company_id or api_key to source control. Use environment variables and reference them from your MCP client configuration. Most clients support $ENV_VAR substitution in config files.

​
Using the MCP server from custom agents

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

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-5",
    max_tokens=4096,
    tools=[
        {
            "type": "computer_20241022",  # placeholder — use mcp tool type
        }
    ],
    mcp_servers=[
        {
            "type": "url",
            "url": "https://api.vh3connect.io/api:kP8T1CK7/mcp",
            "name": "vh3-ai",
            "authorization_token": None,  # auth via headers below
            "extra_headers": {
                "x-vh3-company-id": os.environ["VH3_COMPANY_ID"],
                "x-vh3-api-key": os.environ["VH3_API_KEY"],
            },
        }
    ],
    messages=[{"role": "user", "content": "What needs attention today?"}],
)

​
Tool selection guide for agents

When your agent receives a free-form question and needs to decide which tool to call:
Question patternTool
”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”jobs_feed
”what needs attention / alerts / sentinels”sentinels_run
”generate report / briefing / debrief / weekly summary”reports_generate
”similar to / fault like / what else looks like”search_outcomes
Ambiguous / unclearaggregate_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.