{ "markdown": "

VerifyAX MCP Server

\n\n

\n The official Model Context Protocol (MCP) server for VerifyAX: a cloud-hosted bridge that gives your AI tools secure, real-time access to register agents, generate scenarios, run simulations, and read evaluations on the VerifyAX platform.\n

\n\n\n

\n \"Official\n \"GitHub\n \"License:\n \"Status:\n

\n\n\n

\n \"Model\n \"MCP\n \"Auth:\n \"Hosting:\n

\n\n\n

\n \"Agents\"\n \"Scenarios\"\n \"Simulations\"\n \"Evaluations\"\n

\n\n

\n \n \"verifyax/verifyax-mcp\n \n

\n\n

\n Getting started ·\n Supported tools ·\n Security ·\n Deploy your own ·\n Report an issue\n

\n\n---\n\nThe **official VerifyAX MCP Server** is a bridge between your MCP-compatible AI client and the\n[VerifyAX](https://verifyax.com) agent-evaluation platform. Once configured, it lets you register\nagents, generate scenarios, run simulations, and read evaluations in natural language — without\nwriting API scripts.\n\nWith the VerifyAX MCP Server, you can:\n\n- **Register and test agents** (A2A or API) and confirm connectivity before evaluation.\n- **Generate scenarios** from skill tags and wait for completion in one tool call.\n- **Run evaluations** and read scores, transcripts, and credit usage without manual polling.\n\nIt complements (does not replace) the [`verifyax-api` skill](https://github.com/verifyax/verifyax-plugins):\nthe skill is for developers writing code; the MCP server is for conversational workflows.\n\n## Contents\n\n- [Supported clients](#supported-clients)\n- [Supported tools](#supported-tools)\n- [Before you start](#before-you-start)\n- [Install the MCP server](#install-the-mcp-server)\n- [How it works](#how-it-works)\n- [Example workflows](#example-workflows)\n- [Tips and tricks](#tips-and-tricks)\n- [Data and security](#data-and-security)\n- [Troubleshooting](#troubleshooting)\n- [Support and feedback](#support-and-feedback)\n- [Disclaimer](#disclaimer)\n- [For developers](#for-developers)\n- [License](#license)\n\n---\n\n## Supported clients\n\nThe VerifyAX MCP Server works with MCP-compatible clients that support **Streamable HTTP** or\n**stdio**:\n\n| Client | Setup reference |\n| ------------------------------------- | ----------------------------------------------------------------------------------------------------- |\n| OpenAI ChatGPT | [Connectors / MCP guide](https://platform.openai.com/docs/guides/tools-connectors-mcp) |\n| Claude (Claude.ai, Desktop, and Code) | [Claude MCP docs](https://code.claude.com/docs/en/mcp) |\n| Cursor | [Cursor MCP docs](https://cursor.com/docs/mcp) |\n| Visual Studio Code (GitHub Copilot) | [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) |\n| GitHub Copilot CLI | [About Copilot CLI](https://docs.github.com/en/copilot/concepts/agents/about-copilot-cli) |\n| Google Gemini CLI | [Gemini CLI MCP docs](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md) |\n| Amazon Quick Suite | [MCP integration guide](https://docs.aws.amazon.com/quicksuite/latest/userguide/mcp-integration.html) |\n\nAny client that can connect via [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) can also\nuse the hosted endpoint at `https://mcp.verifyax.com/mcp`.\n\n> [!TIP]\n> For step-by-step Claude setup and how this compares to the VerifyAX skill and SDK, see\n> [`docs/using-verifyax-with-claude.md`](docs/using-verifyax-with-claude.md).\n\n---\n\n## Supported tools\n\nTwelve tools mapped to user intents. Blocking tools poll internally and return only when work\ncompletes (typically 30s–5min).\n\n| Area | Tools | Blocking |\n| -------------- | ----------------------------------------------------------------------------------- | :---------------------------: |\n| **Agents** | `register_agent` · `list_agents` · `delete_agent` | — |\n| **Scenarios** | `list_compatible_tags` · `generate_scenario` · `list_scenarios` · `delete_scenario` | **yes** (`generate_scenario`) |\n| **Evaluation** | `evaluate_agent` · `list_recent_runs` · `get_run_details` | **yes** (`evaluate_agent`) |\n| **Usage** | `get_usage_summary` · `preview_run_cost` | — |\n\n> [!NOTE]\n> For tool descriptions (what Claude reads to pick a tool) and rationale, see\n> [`docs/tool-descriptions.md`](docs/tool-descriptions.md). Package-level reference:\n> [`packages/mcp-server/README.md`](packages/mcp-server/README.md).\n\n---\n\n## Before you start\n\nRequirements depend on how you connect.\n\n### Remote HTTP (hosted at `mcp.verifyax.com`)\n\n- A **VerifyAX API key** (Settings → API Keys in the [console](https://console.verifyax.com))\n- An MCP client with **Streamable HTTP** support, or **Node.js 18+** to run the\n [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) proxy\n\n### Local stdio (`verifyax-mcp-server` via npx)\n\n- **Node.js ≥ 20**\n- A VerifyAX API key in your client config (`VERIFYAX_API_KEY`)\n\nThe npm package exposes two binaries (`verifyax-mcp-server` and `verifyax-mcp-server-http`); pass\nthe stdio binary name explicitly when using `npx`.\n\n---\n\n## Install the MCP server\n\n### Remote HTTP (recommended)\n\nHosted endpoint:\n\n```\nhttps://mcp.verifyax.com/mcp\n```\n\nSend your VerifyAX API key on the initialize request. The hosted server does **not** store keys —\neach client session brings its own.\n\n**Cursor (native URL — v0.48+):**\n\n```json\n{\n \"mcpServers\": {\n \"verifyax\": {\n \"url\": \"https://mcp.verifyax.com/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer sk-ver-api-...\"\n }\n }\n }\n}\n```\n\nDo **not** add a `transport` field — Cursor detects Streamable HTTP from the URL. You can also use\n`\"X-VerifyAX-API-Key\": \"sk-ver-api-...\"` instead of `Authorization`.\n\n**Claude Desktop / clients without native HTTP (`mcp-remote`):**\n\nAdd to `claude_desktop_config.json` (Settings → Developer → Edit Config):\n\n```json\n{\n \"mcpServers\": {\n \"verifyax\": {\n \"command\": \"npx\",\n \"args\": [\n \"-y\",\n \"mcp-remote\",\n \"https://mcp.verifyax.com/mcp\",\n \"--transport\",\n \"http-only\",\n \"--header\",\n \"Authorization:${VERIFYAX_AUTH}\"\n ],\n \"env\": {\n \"VERIFYAX_AUTH\": \"Bearer sk-ver-api-...\"\n }\n }\n }\n}\n```\n\nUse `--transport http-only` because this server speaks Streamable HTTP only (no legacy SSE). You\ncan also pass `X-VerifyAX-API-Key: sk-ver-api-...` via `--header` instead of `Authorization`.\n\nRestart your MCP client after changing config.\n\n### Local stdio\n\n**Claude Code:**\n\n```bash\nclaude mcp add verifyax --env VERIFYAX_API_KEY=sk-ver-api-... -- npx -y -p @verifyax/mcp-server verifyax-mcp-server\n```\n\n**Claude Desktop:**\n\n```json\n{\n \"mcpServers\": {\n \"verifyax\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"-p\", \"@verifyax/mcp-server\", \"verifyax-mcp-server\"],\n \"env\": { \"VERIFYAX_API_KEY\": \"sk-ver-api-...\" }\n }\n }\n}\n```\n\nRestart the client after changing config, then describe what you want in natural language.\n\n---\n\n## How it works\n\n### Architecture and communication\n\n1. Your MCP client connects to `https://mcp.verifyax.com/mcp` (remote HTTP) or spawns\n `npx -p @verifyax/mcp-server verifyax-mcp-server` (local stdio).\n2. The client sends **your** VerifyAX API key on initialize (`Authorization: Bearer …` or\n `X-VerifyAX-API-Key` for HTTP; `VERIFYAX_API_KEY` env for stdio).\n3. The server calls the VerifyAX API on your behalf. Blocking tools (`generate_scenario`,\n `evaluate_agent`) poll job status internally and return only when work finishes.\n\n### Permission and billing\n\n- Actions are scoped to the **workspace** tied to your API key.\n- Usage and credits are billed to **your** VerifyAX workspace, not to the MCP server operator.\n- The hosted server sends **no telemetry** and does not persist API keys between sessions.\n\n### Self-hosting\n\nRun the same HTTP server on your own infrastructure (e.g. Google Cloud Run). See\n[`deploy/gcp/README.md`](deploy/gcp/README.md).\n\n---\n\n## Example workflows\n\nOnce connected, describe tasks in natural language — the client picks the tool.\n\n### Agent setup\n\n- **Register**: _\"Register my A2A agent at https://my-agent.example.com and confirm it's reachable.\"_\n- **List**: _\"What agents are registered in my workspace?\"_\n\n### Scenario authoring\n\n- **Discover tags**: _\"List the skill tags I can use for an interview scenario.\"_\n- **Generate**: _\"Generate an info_exchange scenario tagged empathy and coordination.\"_\n\n### Evaluation\n\n- **Run eval**: _\"Evaluate agent X against scenario Y and summarize the scores.\"_\n- **Review history**: _\"Show details for my most recent simulation run.\"_\n\n### Usage and cost\n\n- **Preview**: _\"How many credits will it cost to run this scenario against my agent?\"_\n- **Summary**: _\"What did my last 5 simulation runs cost?\"_\n\n> [!NOTE]\n> Blocking tools can take 30s–5min. Do not call them repeatedly — wait for the result.\n\n---\n\n## Tips and tricks\n\n### Add defaults to AGENTS.md\n\nReduce discovery calls and bad tag combinations by adding this to an `AGENTS.md` file in your\nproject root (see the [AGENTS.md convention](https://agents.md/) for the format):\n\n```md\n## VerifyAX MCP\n\nWhen connected to verifyax:\n\n- **MUST** call `list_compatible_tags` before `generate_scenario`\n- **MUST NOT** combine QnA tags with other tags (QnA must be the sole tag)\n- **MUST** use `preview_run_cost` when the user asks about credits before `evaluate_agent`\n- Blocking tools (`generate_scenario`, `evaluate_agent`) take 30s–5min — do not retry manually\n```\n\n### Use the skill for code workflows\n\nFor scripts, CI, or custom multi-step logic, use the\n[`verifyax-api` skill](https://github.com/verifyax/verifyax-plugins) or\n[`@verifyax/sdk`](packages/sdk) instead of MCP tools.\n\n---\n\n## Data and security\n\n- All traffic to the hosted endpoint uses **HTTPS (TLS)**.\n- **API key** authentication; every action respects your VerifyAX workspace permissions.\n- The hosted server does **not** store API keys — each session supplies its own.\n- The MCP server sends **no telemetry**; it talks only to the VerifyAX API.\n- Destructive tools (`delete_agent`, `delete_scenario`) permanently remove resources — confirm\n with the user before calling them.\n\nAPI keys are managed in the [VerifyAX console](https://console.verifyax.com) (Settings → API Keys).\nRevoke a key there to cut off access immediately.\n\n---\n\n## Troubleshooting\n\n- **\"VERIFYAX_API_KEY is not set\"** — the key isn't reaching the server. Check the `env` block\n (stdio) or `Authorization` / `X-VerifyAX-API-Key` header (HTTP).\n- **Authentication failed** — the key is invalid, revoked, or from the wrong environment. Mint a\n fresh one in the console.\n- **Tool calls don't appear** — MCP clients load tools at startup; restart the client (or start a\n new session) after adding the server.\n- **HTTP connection fails in Cursor** — try `mcp-remote` with `--transport http-only`, or verify\n the URL ends with `/mcp`.\n- **Want logs?** Set `VERIFYAX_MCP_LOG_LEVEL=debug`. Logs are structured JSON on stderr; stdout is\n reserved for the MCP protocol.\n\n---\n\n## Support and feedback\n\nThis project is maintained by the VerifyAX team at [Conscium](https://conscium.com).\n\n- **Bugs and feature requests:** [open an issue](https://github.com/verifyax/verifyax-mcp/issues)\n- **Development reference:** [`CONTRIBUTING.md`](CONTRIBUTING.md) (maintainers and forks)\n- **External pull requests aren't accepted** — issues are the best way to reach us\n\n---\n\n## Disclaimer\n\nMCP clients can register agents, generate scenarios, run evaluations, and delete resources using\nyour VerifyAX API key and workspace credits. Use least privilege (scoped keys, minimal workspace\naccess), review high-impact actions before confirming, and revoke keys you no longer need.\n\nModel Context Protocol connects AI agents to external tools, which creates powerful workflows but\nalso structural risks. Large language models can be vulnerable to prompt injection and related\nattacks. Only use trusted MCP clients and servers, and review which tools each agent can access.\n\n---\n\n## For developers\n\nThis repository is a pnpm monorepo with two packages:\n\n| Package | Description |\n| --------------------------------------------- | ------------------------------------------------- |\n| [`@verifyax/sdk`](packages/sdk) | Typed TypeScript client for the VerifyAX REST API |\n| [`@verifyax/mcp-server`](packages/mcp-server) | MCP server (12 tools) built on the SDK |\n\nRequires Node ≥ 20 and [pnpm](https://pnpm.io) 10.\n\n```bash\npnpm install # install workspace dependencies\npnpm build # build all packages (topological order)\npnpm test # run unit tests\npnpm lint # lint\npnpm format # format with prettier\n```\n\nNetwork-dependent suites: `pnpm test:integration` (live API, needs `VERIFYAX_TEST_KEY`) and\n`pnpm test:conformance` (spawns the built MCP server over stdio).\n\n- **MCP Inspector:** [`docs/debugging-mcp-inspector.md`](docs/debugging-mcp-inspector.md)\n- **Execution plan:** [`docs/PLAN.md`](docs/PLAN.md)\n- **Architecture decisions:** [`CLAUDE.md`](CLAUDE.md)\n- **Cloud Run deploy:** [`deploy/gcp/README.md`](deploy/gcp/README.md)\n\n---\n\n## License\n\nApache-2.0. See [`LICENSE`](LICENSE).\n", "bytes": 15633, "sha": "85a228bc700621e24b64e6d6e46e007f8a9b2f07cce48a87c4e04c4c7877bb1b", "repo_slug": "verifyax/verifyax-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_verifyax_mcp_server_7572fd37/readme" }