> For the complete documentation index, see [llms.txt](https://docs.testvibe.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.testvibe.com/testvibe-api/mcp-server/mcp.md).

# The TestVibe MCP server

`testvibe mcp` starts a **stdio MCP server** exposing all 23 operations as tools. It ships inside the [CLI package](/testvibe-api/cli/cli.md) and talks to the same REST API with the same key — setup is in [Connect your AI tools](/testvibe-api/getting-started/connect-ai-tools.md).

## Tools

| Tool                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Purpose                                         |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| [`list_projects`](/testvibe-api/api-reference/projects/list_projects.md) / [`get_project`](/testvibe-api/api-reference/projects/get_project.md)                                                                                                                                                                                                                                                                                                                                    | Projects in the workspace.                      |
| [`list_features`](/testvibe-api/api-reference/features/list_features.md) / [`get_feature`](/testvibe-api/api-reference/features/get_feature.md)                                                                                                                                                                                                                                                                                                                                    | Browse features.                                |
| [`create_feature`](/testvibe-api/api-reference/features/create_feature.md) / [`update_feature`](/testvibe-api/api-reference/features/update_feature.md) / [`delete_feature`](/testvibe-api/api-reference/features/delete_feature.md)                                                                                                                                                                                                                                               | Edit features.                                  |
| [`generate_feature`](/testvibe-api/api-reference/generation/generate_feature.md) / [`wait_for_generation`](/testvibe-api/api-reference/generation/wait_for_generation.md) / [`get_generation_status`](/testvibe-api/api-reference/generation/get_generation_status.md) / [`get_generation_log`](/testvibe-api/api-reference/generation/get_generation_log.md) / [`cancel_generation`](/testvibe-api/api-reference/generation/cancel_generation.md)                                 | Drive AI test generation.                       |
| [`run_feature`](/testvibe-api/api-reference/runs/run_feature.md) / [`run_suite`](/testvibe-api/api-reference/runs/run_suite.md) / [`wait_for_run`](/testvibe-api/api-reference/runs/wait_for_run.md) / [`get_run`](/testvibe-api/api-reference/runs/get_run.md) / [`diagnose_run`](/testvibe-api/api-reference/runs/diagnose_run.md) / [`list_runs`](/testvibe-api/api-reference/runs/list_runs.md) / [`get_run_artifacts`](/testvibe-api/api-reference/runs/get_run_artifacts.md) | Run tests, read results, and diagnose failures. |
| [`list_files`](/testvibe-api/api-reference/files/list_files.md) / [`read_file`](/testvibe-api/api-reference/files/read_file.md) / [`write_file`](/testvibe-api/api-reference/files/write_file.md) / [`delete_file`](/testvibe-api/api-reference/files/delete_file.md) / [`list_configs`](/testvibe-api/api-reference/configurations/list_configs.md)                                                                                                                               | Project files and configurations.               |

## Project scoping

Every tool except `list_projects` is **project-scoped**: it takes an optional `project` argument (a public id) and falls back to the configured default (`testvibe use`, `TESTVIBE_PROJECT`, or `.testvibe.json`). Set a default so the model doesn't have to thread the id through every call.

## Designed for agents

* **Tool descriptions carry the workflow.** `generate_feature` tells the model to follow up with `wait_for_generation`; `run_feature` points at `wait_for_run` — an agent can discover the dispatch → poll pattern from the schemas alone.
* **`wait_*` tools poll server-side** (3 s interval, default 120 s / max 170 s per call) so one tool call replaces a polling loop, while staying inside MCP client timeouts. Timing out cancels nothing — the model just calls the tool again.
* **Errors are sentences.** API failures surface the server's human-readable `message`, so the model can correct course ("This feature is already generating.").
* **Tool annotations.** Read-only tools carry `readOnlyHint` and irreversible ones (`delete_feature`, `delete_file`) carry `destructiveHint`, so MCP clients can skip or require confirmation appropriately.
* **`diagnose_run` collapses the fix loop.** One call returns a failed run's failing tests, the Gherkin, the executed spec source, and artifact links — no get-run → read-file → artifacts round trips.

{% hint style="info" %}
**Guardrails are server-side.** The MCP server adds no privileges: the write allowlist, generation locks, and workspace scoping are enforced by the API regardless of what a model asks for. See [Conventions & errors](/testvibe-api/api-reference/conventions.md).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.testvibe.com/testvibe-api/mcp-server/mcp.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.