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.
| 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, 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
| Tool | Description |
|---|---|
list_knowledge_graphs | Returns 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_structure | Returns the classes, attributes, measures and relationships of a knowledge graph, with sample entities. |
search_knowledge_graph | Searches 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_details | Returns the name, synonyms, description and documentation of a concept by its VQL identifier. |
get_vql_documentation | Returns the VQL reference, and the detailed documentation of the functions it refers to. |
run_vql_query | Runs a VQL (Veezoo Query Language) query against a knowledge graph and returns its result. |
ask_veezoo | Hands a natural-language question to Veezoo's own AI. Supports follow-up questions via conversationId. |
run_shared_answer | Executes 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.
Recommended workflow
The server tells connected assistants to answer questions like this:
- Pick the knowledge graph with
list_knowledge_graphs, preferring main knowledge graphs over development branches. - Write the VQL queries themselves: read the structure with
get_knowledge_graph_structure, find the identifiers of concepts and entities withsearch_knowledge_graphandget_concept_details, readget_vql_documentation, and run the queries withrun_vql_query. - Use
ask_veezooto 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
- Go to Admin > API > API Keys.
- Click Create and give the key a descriptive name.
- Pick the user the key should act on behalf of — the key inherits that user's access to knowledge graphs.
- 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-demoknowledge 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 /mcpis supported.GETandDELETEreturn405 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.