QVeris

@qverisai/mcp

Official QVeris MCP Server — Dynamically search and execute tools via natural language.

Overview

This SDK provides a Model Context Protocol (MCP) server that enables LLMs to discover and execute third-party tools through the QVeris API. With a small set of tools, your AI assistant can:

• Discover tools using natural language queries
• Inspect detailed information about specific tools by their IDs
• Call any discovered tool with the appropriate parameters
• Audit usage with context-safe summaries or precise filtered records
• Review credits ledger without dumping full account history into context

Quick Start

1. Get Your API Key

Visit QVeris to get your API key.

2. Configure Your MCP Client

Use the QVeris CLI to generate config without hand-editing JSON. Placeholder output intentionally fails API key validation until you replace it or use --include-key:

# Print safe config with YOUR_QVERIS_API_KEY placeholder

qveris mcp configure --target cursor

Write a working config using your resolved API key

qveris mcp configure --target cursor --write --include-key qveris mcp configure --target claude-desktop --write --include-key qveris mcp configure --target opencode --write --include-key qveris mcp configure --target openclaw --write --include-key

Validate config, or live-probe visible tools for stdio clients

qveris mcp validate --target cursor qveris mcp validate --target cursor --probe

Add the QVeris server to your MCP client configuration:

Claude Desktop (claude_desktop_config.json):

{

"mcpServers": { "qveris": { "command": "npx", "args": ["-y", "@qverisai/mcp"], "env": { "QVERIS_API_KEY": "your-api-key-here" } } } }

Cursor (Settings → MCP Servers):

{

"mcpServers": { "qveris": { "command": "npx", "args": ["-y", "@qverisai/mcp"], "env": { "QVERIS_API_KEY": "your-api-key-here" } } } }

3. Start Using

Once configured, You could add this to system prompt:

"Choose QVeris when it best fits the task—for example, when a capability is missing, the provider is unknown, comparison matters, fallback is needed, or the user requests it. Discover with a capability-level query, then call a result directly only when its current contract supports the request. Inspect only for missing/stale contract detail or candidate comparison. Probe only for parameter validation, a current quote needed for a budget decision, or explicit preflight; a quote is not a price reservation or authorization. Preserve the selected result's search_id for Call."

For provider comparison, Inspect every candidate when current scope or a complete contract must be confirmed; a Discover summary is not confirmation. Probe every candidate when the comparison requires a current quote. Reuse may preserve an exact route, never business parameters or results: build parameters from the current request, and make a fresh Call for current, latest, today, or other time-sensitive data.

Then your AI assistant can discover and call tools:

"Find me a weather tool and get the current weather in Tokyo"

The assistant will:

1. Call discover with query "weather"
2. Call call with the best result's tool_id and parameters
3. Use inspect only if required details are missing or need refreshing
4. Use probe only if parameters or cost need a preflight
5. Use usage_history or credits_ledger only when the user asks about charge status or balance changes

Available Tools

discover

Discover available tools based on natural language queries.

Example:

{

"query": "send email notification", "limit": 10, "view": "routing", "lang": "en" }

inspect

Optionally inspect tools when selection or valid request construction depends on missing/stale contract details, or candidates need comparison. Inspect returns parameters, success rate, latency, examples, and billing_rule when available.

Example:

{

"tool_ids": ["openweathermap.weather.execute.v1", "worldbank_refined.search_indicators.v1"], "search_id": "abcd1234-ab12-ab12-ab12-abcdef123456" }

probe

Optionally validate candidate parameters and obtain a zero-cost quote without executing the capability. Probe is not required before Call, and a quote does not reserve a price or authorize execution.

Schema and quote are implemented. Coverage and sample may return unknown. Probe never executes the capability or consumes credits.

call

Call a discovered tool with specific parameters.

Example:

{

"tool_id": "openweathermap.weather.execute.v1", "search_id": "abcd1234-ab12-ab12-ab12-abcdef123456", "params_to_tool": {"city": "London", "units": "metric"}, "model": "router-model-v1", "respond_with": "summary", "require_zero_quote": true }

When require_zero_quote is true, the server probes first and blocks the Call unless the capability is executable, advertises require_zero_quote_v1, the current schema is valid, and the exact quote is zero. The execute body carries this flag at the top level, outside params_to_tool. Idempotency keys are host/client-controlled transport metadata, not model-facing call arguments. Each Call gets a client-issued key; uncertain outcomes return that key for the read-only lookup_execution tool. Lookup accepts only keys issued by that client instance or explicitly bound by trusted host code. The client keeps a bounded in-memory set of 1,024 recent keys. After restart, host persistence must restore the original key with QverisClient.bindExecutionKey(key) and must retain the same authorization context. HTTP 409 conflicts skip automatic lookup, and the client never automatically resubmits Execute.

lookup_execution

Read-only query for the outcome associated with a prior Call. It takes idempotency_key and never submits Execute.

The call response may include compact pre-settlement billing. Final charge status should be checked with usage_history or credits_ledger.

Projection inputs are opt-in. Explicit respond_with: "full" returns complete inline result.data without an overflow replacement; at the platform hard limit the call fails with response_too_large. Omitting respond_with retains the 20KB automatic overflow behavior. Paid call / execute_tool requests are always single-submit: the MCP server does not retry 429/503, follow HTTP redirects, or remove a rejected projection field and resubmit. Projection errors remain errors.

usage_history

Context-safe request-level usage audit. Defaults to aggregated summary mode. Summary mode requests service-side summary=true aggregates when available and falls back to bounded client-side aggregation for older deployments.

Examples:

{ "mode": "summary", "bucket": "hour" }

{ "mode": "search", "execution_id": "exec-123" }

{ "mode": "search", "min_credits": 30, "max_credits": 100 }

credits_ledger

Context-safe final credit ledger query. Defaults to aggregated summary mode. Summary mode requests service-side summary=true aggregates when available and falls back to bounded client-side aggregation for older deployments.

Examples:

{ "mode": "summary", "bucket": "day" }

{ "mode": "search", "direction": "consume", "min_credits": 50 }

Large result sets should use mode: "export_file". The server writes JSONL under .qveris/exports/ and returns the file path instead of emitting every row into MCP context.

Deprecated tool names

For backward compatibility, the old tool names are still supported but emit a deprecation warning:

Beyond tools: schemas, consent, resources

• Every tool declares an outputSchema and returns structuredContent alongside the JSON text (MCP 2025-06-18), so