Skip to content

docs: MCP server setup for Claude Code, Cursor, Copilot, Antigravity #814

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
slayerjain merged 9 commits into from
Apr 1, 2026
+120 −0
Merged

docs: MCP server setup for Claude Code, Cursor, Copilot, Antigravity #814

Changes from 8 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
a73bc83
docs: add MCP server setup for Claude Code, Cursor, Copilot, Antigravity
slayerjain Mar 31, 2026
58f24b8
fix: address 7 Copilot comments on MCP docs
slayerjain Mar 31, 2026
5b2efeb
fix: specify Copilot MCP config file path (.github/copilot-mcp.json)
slayerjain Mar 31, 2026
afab49a
fix: clarify Copilot MCP config key and document both auth methods
slayerjain Mar 31, 2026
3290442
fix: clarify client-specific config fields, fix internal link path
slayerjain Mar 31, 2026
0b4c61a
fix: clarify MCP vs CLI workflow, tools/list is MCP method
slayerjain Mar 31, 2026
4cdbcf5
fix: remove escaped quotes in inline code
slayerjain Mar 31, 2026
217e767
fix: use distinct heading levels for MCP client configs to avoid TOC …
slayerjain Mar 31, 2026
43cdf85
fix: mention X-API-Key alternative in MCP config examples
slayerjain Mar 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
120 changes: 120 additions & 0 deletions versioned_docs/version-4.0.0/running-keploy/agent-test-generation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,126 @@ Create a `.cursorrules` file in your project root with the same test format refe

Use the same test format documentation as system instructions or project context.

## MCP Server (Recommended for AI Agents)

Keploy provides an MCP (Model Context Protocol) endpoint that gives AI agents **native tool access** to the Automated Test Generation (ATG) platform. Instead of the agent parsing CLI output, it calls structured tools directly and gets typed JSON responses. The CLI workflow described later on this page is an alternative for environments where MCP is not available.

The MCP endpoint is built into the Keploy API server at `/client/v1/mcp`. Tools are auto-generated from the OpenAPI spec—when the API evolves, tools update automatically.

### Available Tools

| Tool | What it does |
| -------------------- | ------------------------------------------------------------------------ |
| `listApps` | List all applications |
| `createApp` | Create a new application |
| `generateTestSuites` | Trigger AI test generation from an OpenAPI spec |
| `runTestSuites` | Execute test suites against a target API |
| `listTestSuites` | List test suites for an app |
| `createTestSuite` | Create a test suite from steps JSON |
| `generate_and_wait` | Generate tests and wait for completion (composite) |
| `run_and_report` | Run tests and return results with failures and coverage gaps (composite) |
| `get_coverage_gaps` | Get uncovered endpoints with prioritized suggestions |
| _...39+ API tools_ | Every `/client/v1` endpoint is available as an MCP tool |

:::caution API Key Security
The examples below include an API key in configuration files. **Do not commit API keys to version control.** Use environment variables or add the config file to `.gitignore`. For CI/CD, use secret management.
:::

Replace `https://your-keploy-host` with your Keploy instance URL (e.g., `https://api.keploy.io` for Keploy Cloud, or your self-hosted domain).

### MCP Client Configuration

#### Claude Code

Add to your Claude Code MCP settings (`~/.claude/settings.json` or project-level). Note: Claude Code requires the `type: url` field (other clients do not).

```json
{
"mcpServers": {
"keploy": {
"type": "url",
"url": "https://your-keploy-host/client/v1/mcp",
"headers": {
Comment on lines +102 to +108
Copy link

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The client config examples use slightly different MCP server schemas (Claude includes type: "url", Cursor/Copilot omit it). If type is required only for Claude, it would help to call that out explicitly; otherwise consider standardizing the examples so readers don’t copy the wrong shape between clients.

Copilot uses AI. Check for mistakes.
"Authorization": "Bearer kep_YOUR_API_KEY"
}
}
Comment on lines +106 to +111
Copy link

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This URL is hardcoded to the Keploy Cloud domain. Since this page targets Keploy Enterprise (including self-hosted), the example should use a placeholder base URL (e.g., https://<your-keploy-host>/client/v1/mcp) and mention that users must replace it with their own API server address.

Copilot uses AI. Check for mistakes.
}
}
```

Copy link

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These examples include an API key in a config file. Please add an explicit warning not to commit credentials and guidance on keeping the file out of version control (or using environment-variable substitution / secret storage if supported by the client). Without that, users may paste real keys into repo-tracked files.

Suggested change
**Security note:** When you replace `kep_YOUR_API_KEY` with a real key, keep this settings file out of version control (for example by using user-specific config locations or adding project-level config files to `.gitignore`), or use your editor/client’s secret storage or environment-variable substitution if available. Avoid committing real API keys to your repositories.

Copilot uses AI. Check for mistakes.
Then ask Claude Code:

> "Use the Keploy MCP tools to generate API tests for my OpenAPI spec, run them against my staging server, and show me coverage gaps"

Claude Code will call `generate_and_wait`, `run_and_report`, and `get_coverage_gaps` tools directly.

#### Cursor

Cursor supports MCP servers. Add to your Cursor MCP configuration (`.cursor/mcp.json`):

```json
{
"mcpServers": {
"keploy": {
"url": "https://your-keploy-host/client/v1/mcp",
"headers": {
"Authorization": "Bearer kep_YOUR_API_KEY"
}
}
Comment on lines +128 to +134
Copy link

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This URL is hardcoded to the Keploy Cloud domain. Since this page targets Keploy Enterprise (including self-hosted), the Cursor example should use a placeholder base URL and mention replacing it with the user’s Keploy API server host.

Copilot uses AI. Check for mistakes.
}
}
```

Cursor's AI agent can then discover and use all Keploy tools natively.

#### GitHub Copilot

GitHub Copilot supports MCP in agent mode. Add to `.github/copilot-mcp.json` in your project (add this file to `.gitignore` since it contains credentials).

> **Note:** GitHub Copilot uses the top-level key `servers` (not `mcpServers` as other clients use). This is Copilot-specific.

```json
{
"servers": {
"keploy": {
"url": "https://your-keploy-host/client/v1/mcp",
"headers": {
"Authorization": "Bearer kep_YOUR_API_KEY"
}
}
Comment on lines +149 to +155
Copy link

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This URL is hardcoded to the Keploy Cloud domain. Since this page targets Keploy Enterprise (including self-hosted), the Copilot example should use a placeholder base URL and mention replacing it with the user’s Keploy API server host.

Copilot uses AI. Check for mistakes.
}
}
```

#### Antigravity

Antigravity (formerly Windsurf) supports MCP servers. Add to your Antigravity MCP settings. Note: Antigravity uses `serverUrl` (not `url`) for the endpoint field.

```json
{
"mcpServers": {
"keploy": {
"serverUrl": "https://your-keploy-host/client/v1/mcp",
"headers": {
"Authorization": "Bearer kep_YOUR_API_KEY"
}
Comment on lines +164 to +171
Copy link

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Antigravity example uses serverUrl while the other client examples use url, but unlike the Copilot section there’s no note explaining this schema difference. Add a short note clarifying that Antigravity expects serverUrl (if that’s intentional), or rename it to url for consistency.

Copilot uses AI. Check for mistakes.
}
Comment on lines +166 to +172
Copy link

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This URL is hardcoded to the Keploy Cloud domain. Since this page targets Keploy Enterprise (including self-hosted), the Antigravity example should use a placeholder base URL and mention replacing it with the user’s Keploy API server host.

Copilot uses AI. Check for mistakes.
}
}
```

### How it Works

1. The agent discovers available tools via the MCP `tools/list` method
2. When you ask "generate API tests", the agent calls `generate_and_wait` with your OpenAPI spec
3. The tool triggers AI generation on the Keploy platform, polls until complete, and returns the created suites
4. The agent calls `run_and_report` to execute suites against your API
5. The tool returns pass/fail results, assertion failures, and coverage gaps
6. The agent reads the coverage gaps and generates additional test suites for uncovered endpoints
7. This loop continues until coverage targets are met

The MCP endpoint uses the same API key as the REST API and accepts the same two authentication methods: `Authorization: Bearer kep_...` or `X-API-Key: kep_...`. See the [Public API docs](/docs/running-keploy/public-api/) for details. All tools proxy to `/client/v1` endpoints using the caller's credentials.
Copy link

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section mentions both Authorization: Bearer ... and X-API-Key: ... auth methods are supported, but the client config examples only show Authorization. Consider adding an X-API-Key variant (or a short note) so readers can copy/paste the alternative auth method more easily.

Copilot uses AI. Check for mistakes.

## Workflow

### 1. Initialize the test directory
Expand Down
Loading