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.14.5 is the latest tested release. It gives agents access to QVeris through six 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

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#

• 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

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.

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#

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:

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

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

6. 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#

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 the best 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