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

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

• A valid QVERIS_API_KEY
• An MCP-compatible client
• 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 and Bearer authentication, with no local package, Node.js process, or server lifecycle to maintain.

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

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

{
  "servers": {
    "qveris": {
      "type": "http",
      "url": "https://mcp.qveris.ai/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key-here"
      }
    }
  }
}

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

Add the endpoint to a remote-MCP-compatible client and 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"
      }
    }
  }
}

Claude Code can 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"

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

For most agent tasks, use this flow:

1. discover to find relevant capabilities
2. inspect to review the best candidate(s) when needed
3. call to execute the selected capability

In practice:

• If the task is simple and the best candidate is obvious, you may go directly from Discover to Call
• If the task is higher risk or parameters are unclear, insert Inspect before Call
• If you already know a good tool_id from a previous turn, re-inspect it before reuse

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