@qverisai/mcp is the official QVeris MCP server for MCP-compatible clients such as Cursor, Claude Desktop, and other coding agents.
It gives agents access to QVeris through three MCP tools:
search_tools = Discoverget_tools_by_ids = Inspectexecute_tool = CallIn other words, the MCP server is the agent-facing transport for the same core QVeris protocol described elsewhere in this repository.
Use the MCP server when:
Use the REST API when:
Both surfaces map to the same QVeris protocol:
| Protocol action | MCP tool | REST API |
|---|---|---|
| Discover | search_tools | POST /search |
| Inspect | get_tools_by_ids | POST /tools/by-ids |
| Call | execute_tool | POST /tools/execute |
18+QVERIS_API_KEYnpxnpx -y @qverisai/mcp
The MCP server reads your API key from:
QVERIS_API_KEY=your-api-key
{
"mcpServers": {
"qveris": {
"command": "npx",
"args": ["-y", "@qverisai/mcp"],
"env": {
"QVERIS_API_KEY": "your-api-key-here"
}
}
}
}
{
"mcpServers": {
"qveris": {
"command": "npx",
"args": ["-y", "@qverisai/mcp"],
"env": {
"QVERIS_API_KEY": "your-api-key-here"
}
}
}
}
For environment-specific setup guides, see:
search_toolsUse this tool to discover capabilities with natural language.
This is the Discover action and is free.
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Natural-language description of the capability you need |
limit | number | No | Max results to return (1-100, default 20) |
session_id | string | No | Session identifier for tracking |
Example:
{
"query": "weather forecast API",
"limit": 10
}
Typical response fields:
search_idtotalresults[]results[].tool_idresults[].paramsresults[].examplesresults[].statsget_tools_by_idsUse this tool to inspect one or more known tool_ids before reuse or execution.
This is the Inspect action.
| Parameter | Type | Required | Description |
|---|---|---|---|
tool_ids | array | Yes | Array of tool IDs to retrieve |
search_id | string | No | Search ID from the discovery that returned the tool(s) |
session_id | string | No | Session identifier for tracking |
Example:
{
"tool_ids": ["openweathermap.weather.execute.v1"],
"search_id": "YOUR_SEARCH_ID"
}
Use get_tools_by_ids when:
The response schema matches /search for the requested tools, including parameters, examples, and stats.
execute_toolUse this tool to call a discovered QVeris capability.
This is the Call action and costs 1-100 credits per invocation, priced by data and task value.
| Parameter | Type | Required | Description |
|---|---|---|---|
tool_id | string | Yes | Tool ID from discovery results |
search_id | string | Yes | Search ID from the discovery that found this tool |
params_to_tool | string | Yes | JSON-stringified parameters to pass to the tool |
session_id | string | No | Session identifier for tracking |
max_response_size | number | No | Max response size in bytes (default 20480) |
Example:
{
"tool_id": "openweathermap.weather.execute.v1",
"search_id": "YOUR_SEARCH_ID",
"params_to_tool": "{\"city\":\"London\",\"units\":\"metric\"}"
}
Typical successful response fields:
execution_idtool_idsuccessresult.dataelapsed_time_ms or execution_timecostFor very large outputs, QVeris may return:
truncated_contentfull_content_file_urlmessageFor most agent tasks, use this flow:
search_tools to discover relevant capabilitiesget_tools_by_ids to inspect the best candidate(s) when neededexecute_tool to call the selected capabilityIn practice:
tool_id from a previous turn, re-inspect it before reuseProviding a consistent session_id across a single user session helps with:
If session_id is omitted, the MCP server may generate one for the lifetime of the server process.
node --versionQVERIS_API_KEY is set correctlytool_id came from a prior discoveryget_tools_by_ids to inspect the tool before callingparams_to_tool is valid JSONIf direct npx execution fails in some clients, wrap with cmd /c:
{
"command": "cmd",
"args": ["/c", "npx", "-y", "@qverisai/mcp"]
}