QVeris MCP Server Documentation

What it is

@qverisai/mcp is the official QVeris MCP server for MCP-compatible clients such as ChatGPT (Codex), Cursor, Claude Desktop, Cherry Studio, GitHub Copilot, Cline, Roo Code, Kiro, Qoder, CodeBuddy, WorkBuddy, and other coding agents.

@qverisai/mcp v0.15.0 is the latest tested release. It gives agents access to QVeris through seven canonical MCP tools:

• discover — Find capabilities by natural language
• inspect — Get detailed tool info (params, success rate, examples)
• probe — Validate parameters and quote without execution
• call — Execute a tool with parameters
• usage_history — Context-safe usage audit summary/search/export
• credits_ledger — Context-safe final credit ledger summary/search/export
• lookup_execution — Read-only outcome lookup using a Call idempotency key

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.

In other words, the MCP server is the agent-facing transport for the same core QVeris protocol described elsewhere in this repository.

MCP vs REST API

Use the MCP server when:

• You are integrating QVeris into ChatGPT (Codex), Cursor, Claude Desktop, Cherry Studio, GitHub Copilot, Cline, Roo Code, Continue, Kiro, Junie, Augment, Zed, Google Antigravity, Qoder, CodeBuddy, WorkBuddy, OpenCode, or another MCP client
• You want the agent to call QVeris tools directly in chat
• You want the client to manage tool invocation automatically

Use the REST API when:

• You are writing application code or backend services
• You need direct HTTP control over requests and responses
• You are building SDK wrappers or production integrations

Both surfaces map to the same QVeris protocol:

Note: The old tool names (search_tools, get_tools_by_ids, execute_tool) are still supported as deprecated aliases.

Requirements for authenticated access

• An MCP-compatible client
• A QVeris account for browser sign-in when using Hosted MCP with OAuth discovery
• A valid QVERIS_API_KEY only for the local stdio setup or the Hosted MCP API-key fallback
• Node.js 18+ only when using the local stdio fallback

For an existing key, keep the Bearer fallback below. An Agent without credentials can explicitly use anonymous Agent registration, then configure its issued key. This issues a trial identity; the default Hosted MCP endpoint still requires OAuth or a key. Start with a Discover-only request and confirm inputs and cost separately before Call. Never put credentials into an installation prompt.

Quick Start

Hosted MCP (recommended)

Prefer Hosted MCP whenever the client supports remote Streamable HTTP. It uses one managed endpoint, with no local package, Node.js process, or server lifecycle to maintain.

For clients with MCP OAuth discovery, add the endpoint below and complete browser sign-in when prompted. You do not need to create or paste an API key. The example uses the mcpServers wrapper; VS Code uses servers instead.

{
  "mcpServers": {
    "qveris": {
      "type": "http",
      "url": "https://mcp.qveris.ai/mcp"
    }
  }
}

If your remote client does not support OAuth discovery, use the Hosted MCP API-key fallback. See the Hosted MCP page for a copy-ready endpoint and client-specific guidance. Use the local stdio setup below only when your client does not support remote Streamable HTTP.

Explicit public read-only Hosted MCP

Use the separate read-only endpoint only for public discovery and inspection:

https://mcp.qveris.ai/mcp/readonly

The default authenticated endpoint remains https://mcp.qveris.ai/mcp, with OAuth discovery and the existing valid-key fallback. Choosing the separate endpoint is explicit; authentication failure never redirects or falls back to read-only access. This hosted mode does not add a new option to the published local @qverisai/mcp package.

Only canonical discover and inspect are listed and callable. Probe, Call, usage/history, ledger, execution lookup, deprecated aliases and resource access are unavailable on this endpoint. Inputs use the public read-only REST contract: restricted public data, no account-specific price or balance, and no identity or trial grant.

Configure a separate uncredentialed remote connection. A present Origin must be explicitly allowed; native clients without Origin can use a service with no allowed browser origins. Authorization, Cookie, session/receipt proofs, query strings and any Mcp-Session-Id are rejected; do not silently remove credentials from an existing authenticated connection. This endpoint allocates no persistent MCP session, and an authenticated session cannot be moved here. It accepts bounded JSON POST requests, not GET/SSE or DELETE; use a client whose HTTP behavior has been verified for this mode. A client being able to list local tool schemas is not evidence that it can invoke public tools.

Requests are limited to 8192 bytes, serialized responses to 512 KiB, and total request lifetime to 15 seconds. Read limits may be shared by clients behind a proxy or common egress; they are not a personal allowance. On 429, honor the returned retry guidance with bounded retries. Report rejected credentials or 401 and connect the intended authenticated identity instead of downgrading. No paid operation is retried or submitted by this mode.

To proceed to Call, explicitly use the authenticated connection, preserve the selected tool/input intent, refresh Inspect, permissions and any necessary quote, then confirm cost. Public discovery context never authorizes Probe/Call. Omit the old public search_id from authenticated Inspect and use its fresh result. An already selected tool does not require another Discover solely for authentication upgrade.

Local stdio fallback

Install via npx

npx -y @qverisai/mcp

The MCP server reads configuration from environment variables:

QVERIS_API_KEY=your-api-key          # Required
QVERIS_BASE_URL=https://qveris.ai/api/v1  # Optional: override API base URL

Configure with QVeris CLI

Use the CLI to generate client config without hand-editing JSON. By default it prints a safe config with YOUR_QVERIS_API_KEY placeholders; placeholder output intentionally fails API key validation until you replace it or use --include-key.

# Print safe Cursor config
qveris mcp configure --target cursor

# Write a working config using the API key from qveris login or QVERIS_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

# Claude Code uses a shell command instead of a JSON config file
qveris mcp configure --target claude-code

Validate a config before restarting the client:

qveris mcp validate --target cursor

For stdio clients, add --probe to start the configured MCP server and confirm that discover, inspect, probe, and call are visible via tools/list:

qveris mcp validate --target cursor --probe

Claude Desktop example

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

Cursor example

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

Cherry Studio example

In Cherry Studio, open Settings → MCP Server, add a server, and enter these values in its configuration fields:

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

Save the server, enable it in the conversation, and confirm that discover, inspect, probe, and call are available.

Desktop agent clients

The following desktop agents should use Hosted MCP when their remote Streamable HTTP connection is available, with local stdio as the fallback: ChatGPT (Codex), GitHub Copilot, Cline, Roo Code, Continue, Kiro, Junie, Augment, Zed, Google Antigravity, Qoder, CodeBuddy, and WorkBuddy, alongside the clients shown above.

For ChatGPT (Codex), run:

codex mcp add qveris --env QVERIS_API_KEY=your-api-key-here --env QVERIS_BASE_URL=https://qveris.ai/api/v1 -- npx -y @qverisai/mcp

For local-stdio-only clients other than GitHub Copilot, open the product's MCP settings and import the fallback configuration below. Zed exposes the same name, command, arguments, and environment fields in its Agent panel.

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

GitHub Copilot in VS Code

GitHub Copilot's mcp.json uses a top-level servers object, not mcpServers.

Hosted MCP configuration

After the QVeris MCP Registry manifest is released and included in the VS Code MCP Gallery, installing QVeris from the Gallery will use the hosted endpoint and discover OAuth automatically. Complete the browser sign-in when prompted. Gallery inclusion is controlled by GitHub; you can also configure the endpoint directly in .vscode/mcp.json:

{
  "servers": {
    "qveris": {
      "type": "http",
      "url": "https://mcp.qveris.ai/mcp"
    }
  }
}

For the API-key fallback in VS Code, keep the servers wrapper and use a password input so the key is stored by VS Code instead of committed to the workspace:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "qveris-api-key",
      "description": "QVeris API key",
      "password": true
    }
  ],
  "servers": {
    "qveris": {
      "type": "http",
      "url": "https://mcp.qveris.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${input:qveris-api-key}"
      }
    }
  }
}

Local stdio fallback

If the client environment cannot use remote HTTP, keep the same servers wrapper and use the local stdio entry instead:

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

For environment-specific setup guides, see:

• SETUP.md
• Codex and ChatGPT desktop setup
• Claude Code setup
• OpenCode setup
• IDE / CLI setup

Hosted MCP details

QVeris provides a remote Streamable HTTP MCP service. It is the preferred MCP connection for clients that support it because it requires no local package or background process.

https://mcp.qveris.ai/mcp

Clients with MCP OAuth discovery can add the endpoint and complete browser sign-in as shown in the quick start, without creating an API key.

API-key fallback

For remote MCP clients without OAuth discovery, use the following configuration to send your QVeris API key on every request:

{
  "mcpServers": {
    "qveris": {
      "type": "http",
      "url": "https://mcp.qveris.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_QVERIS_API_KEY"
      }
    }
  }
}

To use this API-key fallback in Claude Code, add it from the command line:

claude mcp add --transport http qveris https://mcp.qveris.ai/mcp --scope user --header "Authorization: Bearer YOUR_QVERIS_API_KEY"

API-key setup flow:

1. Create a key on Dashboard / API Keys.
2. Add the endpoint and Bearer header to your client. Store the key in a secret or environment variable when supported; never commit it.
3. Reconnect the client and confirm discover, inspect, probe, and call are visible.

The server validates the key when a session starts and binds that session to the credential. A 401 means the key is missing or invalid; a 503 means validation is temporarily unavailable. Start a new MCP session after changing the key. See the Hosted MCP page for a copy-ready setup.

The local stdio package remains available for clients that do not support remote Streamable HTTP MCP.

Available MCP Tools

1. discover

Use this tool to find capabilities with natural language.

This is the Discover action and is free.

Example:

{
  "query": "weather forecast API",
  "limit": 10,
  "view": "routing",
  "lang": "en"
}

Typical response fields:

• search_id
• total
• results[]
• results[].tool_id
• results[].params
• results[].examples
• results[].stats

2. inspect

Use this tool to inspect one or more known tool_ids before reuse or execution.

This is the Inspect action.

Example:

{
  "tool_ids": ["openweathermap.weather.execute.v1"],
  "search_id": "YOUR_SEARCH_ID"
}

Use inspect when:

• Multiple candidates look similar
• You want to re-check parameters before calling
• You want to inspect success rate or latency
• You are reusing a tool found in an earlier turn

The response schema matches /search for the requested tools, including parameters, examples, and stats.

3. probe

For provider OAuth scoped to an end user, pass the optional non-empty sub_user_id to both probe and call, using the same value. Omit it when no sub-user identity is needed; it is not an access token.

Use this tool to validate candidate parameters and obtain a zero-cost quote without executing the capability.

Inputs are tool_id, optional parameters, optional checks (schema, quote, coverage, sample), and optional live_budget (none, metadata, sampled). Schema and quote are implemented; coverage and sample may return unknown. Probe never executes the capability or consumes credits.

4. call

Use this tool to call a discovered QVeris capability.

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

Example:

An explicit respond_with: "full" must return complete inline result.data without truncated_content or a replacement full_content_file_url. If the platform hard safety limit is exceeded, the call fails with response_too_large. When respond_with is omitted, the historical 20KB automatic overflow behavior remains unchanged.

Summary mode preserves at least one usable payload: a summary object, lossless data, or truncated_content together with full_content_file_url. These fields may coexist. Neither statistics nor a URL is guaranteed by the mode alone. Check success first, then field availability; failed summary calls retain an empty data object.

{
  "tool_id": "openweathermap.weather.execute.v1",
  "search_id": "YOUR_SEARCH_ID",
  "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 MCP server probes the current parameters and blocks the Call unless the capability is executable, advertises require_zero_quote_v1, the schema is valid, and the quote is exact and equal to zero. It sends the flag at the top level of the execute request. Idempotency keys are host/client-controlled transport metadata and are not accepted in model-facing call arguments. The client generates a key and returns it with uncertain outcomes so it can be reused with lookup_execution. Lookup accepts only keys issued by that client instance or explicitly bound by trusted host code. The client retains a bounded in-memory set of 1,024 recent keys; after a process restart, the host must restore its own saved key with QverisClient.bindExecutionKey(key) under the same authorization context before lookup. It never automatically submits a second Call. HTTP 409 conflicts skip automatic lookup; use lookup_execution explicitly to avoid confusing a previous result with this request.

Projection inputs are opt-in. Paid call / execute_tool requests are strict 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; QVERIS_MAX_RETRIES applies only to read and audit tools.

Typical successful response fields:

• execution_id
• tool_id when returned by the selected projection
• success
• result.data, or compact summary fields when requested
• elapsed_time_ms or execution_time
• billing / pre_settlement_bill when available

5. lookup_execution

Read-only lookup for the outcome associated with an earlier Call. It never submits or retries Execute.

The response may report pending, completed, failed, or unavailable. Query again with the same key when needed; completed includes the original Call response when available.

6. usage_history

Use this tool when the user asks whether a call succeeded, failed, or charged credits. It defaults to summary mode and does not dump full history into context.

Useful inputs:

• mode: summary, search, or export_file
• execution_id or search_id for precise lookup
• charge_outcome for charged, included, failed_not_charged, or failed_charged_review
• min_credits / max_credits for amount ranges
• start_date / end_date for time windows

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

7. credits_ledger

Use this tool when the user asks why their balance changed. It defaults to summary mode.

Useful inputs:

• mode: summary, search, or export_file
• direction: consume, grant, or any
• entry_type
• min_credits / max_credits
• start_date / end_date

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 MCP server writes JSONL under .qveris/exports/ and returns the file path instead of emitting every row.

For very large call outputs, QVeris may return:

• truncated_content
• full_content_file_url
• message

Recommended Usage Pattern

Copied service/task context

If a user pastes a v1 JSON context copied from the installation page, route it through the canonical CLI consumer:

qveris call --context @context.json --params @params.json

The context contains public IDs and expiry only; it contains no parameters or authorization. The CLI rejects sensitive/executable content and unsupported required capabilities, ignores ordinary future fields with warnings, and refreshes expired availability/price/permission snapshots. It uses Inspect or Probe only when current validation needs them, and a service-only context returns candidates without guessing. Do not translate the JSON directly into an MCP call or reuse an old search_id.

If the workflow must stay inside MCP, apply the same policy manually: use public IDs only as search hints, Discover again, return candidates for service-only context, require an exact current tool match, Inspect or Probe only when contract/parameter/pricing validation needs it, and Call with the fresh search_id. Use usage_history and credits_ledger to resolve final settlement; missing final audit data means settlement is unknown.

Choose between connected tools and QVeris by task fit, data quality/freshness, cost, user constraints, and call overhead. QVeris is especially useful when a capability is missing, the provider is unknown, cross-provider comparison matters, fallback is needed, or the user requests it; it is not a mandatory gateway.

For most QVeris tasks, use this flow:

1. discover to find relevant capabilities
2. call a suitable candidate directly when discovery provides enough schema and cost information

In practice:

• Use inspect only when selection or valid request construction depends on missing/stale contract details, or candidates need comparison
• Use probe only when parameters need validation, a current quote is needed for a budget decision, or preflight is explicitly requested; a quote is not a price reservation or authorization
• Preserve the current Discover result's search_id for Call and rebuild parameters from the user's current request
• The MCP server does not provide semantic route memory. If the host implements it, isolate it by account/API endpoint/authorization/session, expire schema/pricing/availability independently, and never cache credentials, sensitive values, or business results

Session Management

Providing a consistent session_id across a single user session helps with:

• User-session continuity
• Better tool selection over time
• More coherent analytics and tracing

If session_id is omitted, the MCP server may generate one for the lifetime of the server process.

Troubleshooting

MCP server does not appear in the client

• Confirm Node.js is installed: node --version
• Confirm the client MCP config is valid JSON
• Confirm QVERIS_API_KEY is set correctly
• Restart the MCP client after configuration changes

Tools are visible but calls fail

• Verify the API key is valid
• Verify the selected tool_id came from a prior discovery
• Re-run inspect to inspect the tool before calling
• Check that params_to_tool is a valid object

Windows-specific issues

If direct npx execution fails in some clients, wrap with cmd /c:

{
  "command": "cmd",
  "args": ["/c", "npx", "-y", "@qverisai/mcp"]
}

Related Docs

• Getting started
• REST API documentation
• Agent setup guide
• MCP/client skill definition