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

Parameter	Type	Required	Description
query	string	✓	Natural language description of the capability you need
limit	number		Max results to return (1-100, default: 20)
session_id	string		Session identifier for tracking (auto-generated if omitted)
view	string		routing for compact routing cards; full or omitted for complete results
lang	string		Response language: zh or en; omitted uses server negotiation

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.

Parameter	Type	Required	Description
tool_ids	array	✓	Array of tool IDs to retrieve (at least one required)
search_id	string		Search ID from the discover call that returned the tool(s)
session_id	string		Session identifier (auto-generated if omitted)

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.

Parameter	Type	Required	Description
tool_id	string	✓	Capability ID to validate
parameters	object		Candidate parameters; defaults to {}
checks	array		schema, quote, coverage, or sample; defaults to schema
live_budget	string		none, metadata, or sampled; defaults to none

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.

Parameter	Type	Required	Description
tool_id	string	✓	Tool ID from discover results
search_id	string	✓	Search ID from the discover call that found this tool
params_to_tool	object	✓	A dictionary of parameters to pass to the tool
session_id	string		Session identifier (auto-generated if omitted)
model	string		Model that selected and parameterized the call (maximum 128 characters)
max_response_size	number		Automatic inline limit in UTF-8 bytes (default: 20480; -1 is unlimited); explicit full takes precedence over a finite value
respond_with	string		Omit for compatibility auto-delivery; use full to force complete inline data, summary, or fields:<JSONPath,...>

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"
}

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.

Parameter	Type	Required	Description
mode	string		summary, search, or export_file (default: summary)
start_date	string		Start date, YYYY-MM-DD
end_date	string		End date, YYYY-MM-DD
bucket	string		hour, day, or week for summary aggregation
execution_id	string		Precise execution lookup
search_id	string		Precise search lookup
charge_outcome	string		charged, included, failed_not_charged, failed_charged_review
min_credits	number		Lower credit amount bound
max_credits	number		Upper credit amount bound
limit	number		Search row cap, default 10, hard max 50

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.

Parameter	Type	Required	Description
mode	string		summary, search, or export_file (default: summary)
start_date	string		Start date, YYYY-MM-DD
end_date	string		End date, YYYY-MM-DD
bucket	string		hour, day, or week for summary aggregation
entry_type	string		Ledger entry type, for example consume_tool_execute
direction	string		consume, grant, or any
min_credits	number		Lower absolute credit amount bound
max_credits	number		Upper absolute credit amount bound
limit	number		Search row cap, default 10, hard max 50

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:

Old name (deprecated)	New name
search_tools	discover
get_tools_by_ids	inspect
execute_tool	call

Beyond tools: schemas, consent, resources

• Every tool declares an outputSchema and returns structuredContent alongside the JSON text (MCP 2025-06-18), so clients get typed results.
• With QVERIS_MCP_CONFIRM_CALLS=true, a charged call first asks the user to confirm via MCP elicitation (billing consent); declining cancels the call before any credits are spent. Off by default.
• Resources: read qveris://server-card for the server's identity card, or qveris://capability/{tool_id} for a capability's full metadata (parameters, examples, stats, billing) without spending a tool call.

Session Management

Providing a consistent session_id in a same user session in any tool call enables:

• Consistent user tracking across multiple tool calls
• Better analytics and usage patterns
• Improved tool recommendations over time

If not provided, the SDK automatically generates and maintains a session ID for the lifetime of the server process. However, this result in a much larger granularity of user sessions.

The MCP server keeps one generated session_id for its process when callers omit one, but it does not implement semantic route memory or persistent schema caching. A host may add explicit per-user/session reuse, but must isolate it by account, API endpoint, authorization context, and session; preserve the original search_id; rebuild business parameters from the current request; and expire schema, pricing, and availability independently. Never store credentials, sensitive parameter values, or business results in capability memory. Without such a host implementation, Discover again rather than assuming remembered state exists.

Response Handling

Successful Execution

{
  "execution_id": "abcd1234-ab12-ab12-ab12-abcdef123456",
  "tool_id": "openweathermap.weather.execute.v1",
  "success": true,
  "result": {
    "data": {
      "temperature": 15.5,
      "humidity": 72,
      "description": "partly cloudy"
    }
  },
  "execution_time": 0.847
}

Large Responses

When respond_with is omitted and tool output exceeds max_response_size, you'll receive:

{
  "result": {
    "message": "Result content is too long...",
    "truncated_content": "[[1678233600000, \"22198.56...",
    "full_content_file_url": "https://..."
  }
}

The full_content_file_url is valid for 120 minutes.

Transport modes

The server speaks two MCP transports from the same binary:

• stdio (default) — used by Claude Desktop, Cursor and other local clients. No change to existing configs.
• Streamable HTTP — for remote deployment (e.g. Claude Desktop Custom Connectors, hosted/edge runtimes). Each client session gets its own session id (Mcp-Session-Id header), managed automatically.

Enable HTTP mode with any of --http, QVERIS_MCP_TRANSPORT=http, or by setting an HTTP port/host:

# Local only (loopback): no inbound auth required
QVERIS_API_KEY=sk-... npx -y @qverisai/mcp --http --port 3000

# Exposed: bind all interfaces, require a bearer token, allow-list the public host
QVERIS_API_KEY=sk-... \
QVERIS_MCP_TRANSPORT=http \
QVERIS_MCP_HTTP_HOST=0.0.0.0 \
QVERIS_MCP_HTTP_AUTH_TOKEN=$(openssl rand -hex 32) \
QVERIS_MCP_ALLOWED_HOSTS=mcp.example.com \
npx -y @qverisai/mcp

• The endpoint is POST/GET/DELETE {path} (default /mcp); GET /health returns an unauthenticated liveness probe.
• Inbound auth: set QVERIS_MCP_HTTP_AUTH_TOKEN to require Authorization: Bearer <token> on the MCP endpoint. The server refuses to start when binding a non-loopback host without a token, unless you set QVERIS_MCP_HTTP_ALLOW_UNAUTHENTICATED=true to delegate auth to an external proxy/gateway. Your QVERIS_API_KEY is the server's outbound credential to QVeris — it is not an inbound check, so anyone reaching an unauthenticated endpoint would spend your credits.
• Embedding API: the package root exports startHttpServer, resolveTransportConfig, QverisClient, and the session-auth types. An independently operated service can set requireSessionBearer on its resolved transport config and provide an asynchronous session factory. The transport requires a bearer, passes it only to that factory, stores only a credential fingerprint for session binding, and rejects credential changes. A hosted embedding can call createQverisServer(client, sessionId, { includeDeprecatedAliases: false }) to advertise only the six canonical tools; deprecated aliases remain callable for cached legacy clients. The embedding service owns validation, client construction, rate limits, deployment, and operations.
• DNS-rebinding protection is on by default (localhost + the bound host/port are allow-listed). When exposing the server publicly, add your public host via QVERIS_MCP_ALLOWED_HOSTS.
• Requests are capped at 4 MiB by default (QVERIS_MCP_MAX_BODY_BYTES), and idle sessions are evicted after 5 minutes (QVERIS_MCP_SESSION_TIMEOUT_MS).
• Discovery: registries and crawlers can learn about the server without connecting:
  • Server Card at GET {path}/server-card (default /mcp/server-card), media type application/mcp-server-card+json — server identity, version, and the remote endpoint.
  • MCP Catalog at GET /.well-known/mcp/catalog.json — a site-wide index pointing at the Server Card.
  • Both are public (unauthenticated, CORS-enabled), even when an auth token is set. Behind a TLS proxy, set QVERIS_MCP_PUBLIC_URL (or send X-Forwarded-Proto) so the advertised URLs use your public origin.
  • Auth metadata: hosted deployments can advertise how to authenticate by setting remoteHeaders on the ServerCardInfo they pass to startHttpServer — typically bearerAuthHeaderInput() (exported from the package root), which declares an Authorization: Bearer {api_key} template whose variable is marked required + secret so discovery clients prompt for the key and store it securely. buildServerCard rejects literal secret material: secret header values must stay {variable} templates and secret variables cannot carry a value/default. Each deployment's card must reference only its own endpoint — never a sibling site's URLs.
  • Schema status (experimental): the card follows the MCP Server Card experimental extension (SEP-2127). Its public $schema URL (static.modelcontextprotocol.io/schemas/v1/server-card.schema.json) is the canonical versioned location but is not published upstream yet, so generated cards are validated in CI against a schema vendored at a pinned upstream commit (schemas/README.md); a separate non-blocking CI step probes the public URL and reports availability/drift.
• This package does not implement a hosted OAuth authorization server. Independently operated HTTP deployments own credential validation and session policy through the embedding/session-auth hooks described above.

Environment Variables

Variable	Required	Description
QVERIS_API_KEY	✓	Your QVeris API key
QVERIS_BASE_URL		Override the built-in API base URL
QVERIS_MAX_RETRIES		Read-operation retries for rate-limited (429) / transient (503) responses (default 3; 0 disables). Paid calls never inherit this setting.
QVERIS_MCP_TRANSPORT		stdio (default) or http
QVERIS_MCP_HTTP_PORT		HTTP port (default 3000; setting it implies HTTP mode)
QVERIS_MCP_HTTP_HOST		HTTP bind host (default 127.0.0.1)
QVERIS_MCP_HTTP_PATH		MCP endpoint path (default /mcp)
QVERIS_MCP_ALLOWED_HOSTS		Comma-separated extra Host values to allow (for DNS-rebinding protection)
QVERIS_MCP_ALLOWED_ORIGINS		Comma-separated extra Origin values to allow
QVERIS_MCP_DNS_REBINDING_PROTECTION		true (default) / false
QVERIS_MCP_HTTP_JSON		true to return JSON responses instead of SSE (default false)
QVERIS_MCP_HTTP_AUTH_TOKEN		Require Authorization: Bearer <token> on the MCP endpoint
QVERIS_MCP_HTTP_ALLOW_UNAUTHENTICATED		true to allow a non-loopback bind without a token (auth delegated externally)
QVERIS_MCP_MAX_BODY_BYTES		Max request body size in bytes (default 4194304)
QVERIS_MCP_SESSION_TIMEOUT_MS		Idle session TTL in ms (default 300000)
QVERIS_MCP_CONFIRM_CALLS		true to ask the user (via MCP elicitation) before each charged call; clients without elicitation proceed as before
QVERIS_MCP_PUBLIC_URL		Public origin advertised in discovery documents (e.g. https://mcp.example.com)

API Endpoint Override

The server uses its built-in API endpoint unless QVERIS_BASE_URL is set. API key prefixes and other environment variables do not select an endpoint. To target a custom endpoint, set QVERIS_BASE_URL in your MCP client config:

{
  "mcpServers": {
    "qveris": {
      "command": "npx",
      "args": ["-y", "@qverisai/mcp"],
      "env": {
        "QVERIS_API_KEY": "your-api-key",
        "QVERIS_BASE_URL": "https://qveris.ai/api/v1"
      }
    }
  }
}

The override must be an HTTP(S) URL without credentials, a query string, or a fragment.

Examples

examples/agent-loop.ts drives this server over stdio the way an agent runtime does: spawn it, list the tools, then run the default discover → call path. It is safe to run without an API key (tool listing works unconfigured), and the call step is gated behind RUN_QVERIS_CALLS=1.

Requirements

• Node.js 18.0.0 or higher
• A valid QVeris API key (qveris.ai)

Development

# Clone the repository
git clone https://github.com/QVerisAI/qveris-agent-toolkit.git
cd qveris-agent-toolkit/packages/mcp

# Install dependencies
npm install

# Build
npm run build

# Run locally
QVERIS_API_KEY=your-key node dist/index.js

License

MIT © QVerisAI

Support

• 🐛 Issue Tracker
• 💬 Contact: contact@qveris.ai