MCP (Model Context Protocol)

Veezoo exposes a Model Context Protocol (MCP) server that lets AI assistants such as Claude Desktop, Cursor, or any MCP-compatible client query your knowledge graphs directly.

Overview

MCP is an open protocol, developed by Anthropic, for connecting AI models to external tools and data sources. Once you connect a client to Veezoo's MCP server, the assistant can list your knowledge graphs, ask natural-language questions, run VQL queries, and execute shared answers — all scoped to whatever the API key is allowed to access.

Property	Value
Endpoint	<your-veezoo-url>/mcp
Transport	Streamable HTTP (JSON-RPC 2.0 over HTTPS POST)
Authentication	Veezoo API key
Protocol version	2025-11-25

<your-veezoo-url> is the base URL you use to access Veezoo — for example https://app.veezoo.com, or https://<subdomain>.app.veezoo.com if your organization is on a dedicated subdomain.

Available Tools

Tool	Description
list_knowledge_graphs	Returns every knowledge graph the API key can see, with its ID, name, and default language.
ask_question	Asks a natural-language question against a specific knowledge graph. Supports follow-up questions via conversationId.
run_vql_query	Executes a VQL (Veezoo Query Language) query directly against a knowledge graph.
run_shared_answer	Executes a pre-configured shared answer by its ID.

All tool calls except list_knowledge_graphs require a kgId argument. Permissions are enforced per knowledge graph based on the API key's owner.

Getting an API Key

1. Go to Admin > API > API Keys.
2. Click Create and give the key a descriptive name.
3. Pick the user the key should act on behalf of — the key inherits that user's access to knowledge graphs.
4. Copy the key when it is displayed (this is the only time it will be shown).

See the API Keys documentation for more details on scoping.

Connecting an MCP Client

The endpoint uses the standard MCP Streamable HTTP transport with a bearer token. Most MCP clients expect a JSON configuration snippet — here are the most common ones.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "veezoo": {
      "url": "<your-veezoo-url>/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Restart Claude Desktop. The Veezoo tools appear in the tools panel of a new conversation.

Cursor

Open Cursor's Settings > MCP and add a new server:

{
  "veezoo": {
    "url": "<your-veezoo-url>/mcp",
    "headers": {
      "Authorization": "Bearer YOUR_API_KEY"
    }
  }
}

Generic HTTP Clients

If your client does not support the bearer-header syntax above, X-Api-Key is accepted as well:

{
  "url": "<your-veezoo-url>/mcp",
  "headers": {
    "X-Api-Key": "YOUR_API_KEY"
  }
}

Testing the Endpoint Manually

A direct JSON-RPC call is useful to confirm the key works before wiring up a client:

curl -X POST <your-veezoo-url>/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

A successful response returns the four tools described above.

Example Prompts

Once connected, you can prompt the assistant naturally and it will pick the right tool:

• "List my Veezoo knowledge graphs."
• "Using the sales-demo knowledge graph, how many customers do we have by region?"
• "Run this VQL against sales-demo: var c from kb.Customer; select(count(c))."

Limitations

• Only POST /mcp is supported. GET and DELETE return 405 Method Not Allowed — the server does not keep long-lived SSE sessions.
• Tool responses are JSON. Chart rendering and follow-up suggestions that appear in the Veezoo chat UI are not returned to MCP clients.
• Rate limits and request-body size limits match the REST API.

Troubleshooting

401 Unauthorized

Check that the Authorization: Bearer … or X-Api-Key header is set and that the key has not been revoked. Keys whose owner has been deleted or demoted below admin are deactivated automatically — recreate the key under an active admin user.

The assistant says it can't find a knowledge graph

Call list_knowledge_graphs first (or ask the assistant to). The kgId is case-sensitive and must match exactly. Knowledge graphs the key's user does not have Read permission on are filtered out.

run_vql_query returns VQL query failed

The VQL was parsed or executed against the database but failed — the error message is sanitized. Run the same VQL in the Veezoo Query Editor for the full error.