@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:
discover — Find capabilities by natural languageinspect — Get detailed tool info (params, success rate, examples)call — Execute a tool with parametersIn 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 | discover | POST /search |
| Inspect | inspect | POST /tools/by-ids |
| Call | call | POST /tools/execute |
Note: The old tool names (
search_tools,get_tools_by_ids,execute_tool) are still supported as deprecated aliases.
18+QVERIS_API_KEYnpxnpx -y @qverisai/mcp
The MCP server reads configuration from environment variables:
QVERIS_API_KEY=your-api-key # Required
QVERIS_REGION=cn # Optional: force region (global | cn)
QVERIS_BASE_URL=https://... # Optional: override API base URL
Region is auto-detected from your API key prefix (sk-cn-xxx → China, sk-xxx → Global). Set QVERIS_REGION only if you need to override.
{
"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 users in mainland China, add QVERIS_REGION or use a sk-cn- prefixed key:
{
"mcpServers": {
"qveris": {
"command": "npx",
"args": ["-y", "@qverisai/mcp"],
"env": {
"QVERIS_API_KEY": "sk-cn-your-api-key-here",
"QVERIS_REGION": "cn"
}
}
}
}
For environment-specific setup guides, see:
discoverUse this tool to find 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[].statsinspectUse 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 inspect when:
The response schema matches /search for the requested tools, including parameters, examples, and stats.
callUse 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 | object | Yes | Dictionary of 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:
discover to find relevant capabilitiesinspect to review the best candidate(s) when neededcall to execute 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 a valid objectIf direct npx execution fails in some clients, wrap with cmd /c:
{
"command": "cmd",
"args": ["/c", "npx", "-y", "@qverisai/mcp"]
}