Veezoo

Connecting from MCP Clients

Connect MCP-compatible clients such as Claude Desktop or Cursor to Veezoo to list knowledge graphs, ask questions, and run VQL queries.

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.

To give Veezoo access to tools of remote MCP servers, see Connecting to MCP Servers.

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, explore them, write and run VQL queries, hand questions to Veezoo, and execute shared answers — all scoped to whatever the API key is allowed to access.

PropertyValue
Endpoint<your-veezoo-url>/mcp
TransportStreamable HTTP (JSON-RPC 2.0 over HTTPS POST)
AuthenticationVeezoo API key
Protocol version2025-11-25, 2025-06-18 or 2025-03-26, whichever the client requests (2025-11-25 if it requests another one)

<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

ToolDescription
list_knowledge_graphsReturns every knowledge graph the API key can see, with its ID, name, and languages. A development branch also has the mainKgId of its main knowledge graph, if the API key can see the main knowledge graph too.
get_knowledge_graph_structureReturns the classes, attributes, measures and relationships of a knowledge graph, with sample entities.
search_knowledge_graphSearches a knowledge graph by text for concepts and entities, e.g. to find the VQL identifier of a customer, optionally within one class (classId).
get_concept_detailsReturns the name, synonyms, description and documentation of a concept by its VQL identifier.
get_vql_documentationReturns the VQL reference, and the detailed documentation of the functions it refers to.
run_vql_queryRuns a VQL (Veezoo Query Language) query against a knowledge graph and returns its result.
ask_veezooHands a natural-language question to Veezoo's own AI. Supports follow-up questions via conversationId.
run_shared_answerExecutes a pre-configured shared answer by its ID.

All tool calls except list_knowledge_graphs and get_vql_documentation require a kgId argument. Permissions are enforced per knowledge graph based on the API key's owner. The knowledge graph tools and ask_veezoo take an optional language and otherwise use the user's language in the knowledge graph, as the Veezoo chat does. run_shared_answer always uses the user's language.

ask_veezoo was called ask_question before. Clients that call the tool by name need to use the new name.

The server tells connected assistants to answer questions like this:

  1. Pick the knowledge graph with list_knowledge_graphs, preferring main knowledge graphs over development branches.
  2. Write the VQL queries themselves: read the structure with get_knowledge_graph_structure, find the identifiers of concepts and entities with search_knowledge_graph and get_concept_details, read get_vql_documentation, and run the queries with run_vql_query.
  3. Use ask_veezoo to let Veezoo answer the question instead, or to get help, e.g. by asking it to only write the VQL without running it.

Query results

run_vql_query returns all rows of a result up to the row limit of the database, and truncated tells whether that limit cut rows off. Large results can be big: aggregate, filter or sort in VQL where the full rows aren't needed.

Asynchronous questions

Clients that support MCP tasks can run ask_veezoo without keeping the original HTTP request open. The tool advertises optional task execution: include a task object in the tools/call parameters, poll the returned task ID with tasks/get, and retrieve the completed tool response with tasks/result.

Tasks and their results are retained for up to one hour from task creation by default. A client can request a different lifetime with task.ttl (in milliseconds), up to 24 hours. Clients without MCP task support continue to call ask_veezoo synchronously.

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