Configure your AI assistant on Grafana Labs

Bootstrap your editor with k6 x agent

Mon, 21 Sep 2026 15:16:28 +0000

Bootstrap your editor with k6 x agent

The k6 x agent command scaffolds an AI-assisted k6 testing workflow in your project. A single invocation drops portable SKILL.md bundles into your editor’s expected locations and registers the k6 MCP server in your editor’s MCP configuration — so you don’t have to author MCP client configuration by hand.

k6 x agent is a subcommand extension shipped with k6. The first time you run it, k6 transparently fetches the extension; subsequent invocations start immediately.

What `k6 x agent init` does for you

For each editor you target, init will:

Install bundled skills: Write portable SKILL.md files (or the editor’s equivalent rule format) into the locations your editor reads from. Skills auto-activate based on user intent, for example “write a smoke test” or “convert this Playwright script”.
Register the k6 MCP server: Surgically merge a k6 entry into the editor’s MCP config (.mcp.json, .cursor/mcp.json, .vscode/mcp.json, …) so your assistant can call validate_script, run_script, and the rest of the k6 MCP tools.
Stay out of your way: Files written by k6 x agent carry an ownership marker. Re-running init is idempotent. Files you’ve edited locally are never overwritten unless you pass --force.

Prerequisites

k6 v2.0 or later on your PATH (install k6).
A project directory you want to scaffold into (run the command from the project root).
One of the editors in Supported targets.

Quickstart

From the root of your k6 project:

k6 x agent init claude-code           # one editor
k6 x agent init claude-code cursor    # several
k6 x agent init --all                 # every supported target
k6 x agent status                     # verify what got installed

Then open your editor and ask it to plan or write a k6 test. The bundled skills auto-activate based on intent — for example, “write a smoke test for the login flow” or “convert this Playwright script to k6”.

Note
Before any disk writes, you can run k6 x agent init --dry-run <target> to preview every file the command would create or merge, with byte counts and write modes.

Supported targets

Target	CLI name	Skills location	MCP config
Claude Code	`claude-code`	`.claude/skills/<name>/`	`.mcp.json` + `.claude/settings.local.json`
OpenCode	`opencode`	`.opencode/skills/<name>/`	`opencode.json`
OpenAI Codex CLI	`codex-cli`	`.codex/skills/<name>/`	`.codex/mcp.json`
GitHub Copilot	`vscode-copilot`	`.github/copilot/skills/<name>/`	`.vscode/mcp.json`
Cursor	`cursor`	`.cursor/rules/<name>.mdc`	`.cursor/mcp.json`
Cline	`cline`	`.clinerules/<name>.md`	global (snippet printed as a notice)

Note
Cline’s MCP configuration is global rather than project-scoped. k6 x agent init cline prints the JSON snippet you need to paste into cline_mcp_settings.json instead of writing it for you.

If your editor isn’t listed, see Editors not supported by k6 x agent below for manual setup.

Bundled skills

The skills below are embedded in the binary and installed for every target. They are written in portable SKILL.md format and auto-activate when your assistant detects matching intent in the conversation.

Skill	Triggers on
`k6-test-planner`	“plan tests”, “design a test strategy”, “what k6 tests should I write”
`k6-load-test`	“write a k6 script”, “load test”, “stress / soak / spike test”
`k6-smoke-test`	“smoke test”, “sanity check”, “quick health check”
`k6-browser-test`	“browser test”, “UI test with k6”, “test the frontend”
`k6-playwright-converter`	A Playwright script that needs to be ported to `k6/browser`

Run k6 x agent skills show <name> to print a skill’s full SKILL.md to stdout.

Commands

Command	Description
`k6 x agent init <target>...`	Write or update files for one or more targets.
`k6 x agent init --all`	Initialize every registered target.
`k6 x agent status`	Show what is installed in the current workspace.
`k6 x agent list`	List available targets and bundled skills.
`k6 x agent skills list`	List skills shipped in the binary.
`k6 x agent skills show <name>`	Print a skill’s `SKILL.md` to stdout.

`init` flags

Flag	Description
`--all`	Apply to every registered target. Cannot be combined with positional target names.
`--force`	Overwrite a managed file even if it has been edited locally.
`--dry-run`	Print the plan (paths, write modes, sizes) without touching disk.

Example status output

Agent installation status

[+] Claude Code
   - .mcp.json detected
[-] Cursor
   - Missing: .cursor/mcp.json
   - Hint: k6 x agent init cursor

[+] k6 MCP support
   - Found at /usr/local/bin/k6

A [+] next to k6 MCP support confirms that the editor will be able to launch k6 x mcp when your assistant connects.

Safety

k6 x agent is conservative about what it writes:

It never creates or modifies user-owned top-level files such as AGENTS.md or README.md.
For shared JSON config files (.mcp.json, .cursor/mcp.json, .vscode/mcp.json, opencode.json), only the k6 entry is touched. Other servers and unrelated keys in the file are preserved.
Files inside xk6-subcommand-agent-owned folders are stamped with an ownership marker. Re-running init is idempotent, and --force is required to overwrite a file you have edited locally.
--dry-run prints the full plan before any disk write, so you can review every path and write mode up front.

For the full design, see xk6-subcommand-agent/docs/DESIGN.md.

Troubleshooting

folder already exists or file collision — re-run with --force to overwrite managed files. k6 x agent never deletes files it does not own.
Status shows [-] k6 MCP support — k6 is not on the editor’s PATH. Install k6 from Install k6, and make sure your editor is launched in a shell that can find it.
Cline MCP entry missing — Cline’s MCP configuration is global. Copy the JSON snippet printed by k6 x agent init cline into cline_mcp_settings.json.
Unsupported editor — see Editors not supported by k6 x agent for manual MCP setup guidance.

Editors not supported by `k6 x agent`

If your editor or MCP client isn’t in the Supported targets table, you can still register the k6 MCP server manually — it works with any client that speaks stdio.

Before you start:

If you launch the server via the k6 subcommand (k6 x mcp), ensure k6 is on your PATH.
If you launch the standalone mcp-k6 binary, ensure both mcp-k6 and k6 are on your PATH.
If you launch the server in Docker, ensure Docker is installed and running.

How MCP works

The Model Context Protocol (MCP) is a standard way for AI assistants to communicate with external tools. At its core, an MCP server is a program that:

Reads JSON-RPC messages from stdin.
Writes JSON-RPC responses to stdout.
Advertises tools, resources, and prompts that the AI can use.

When you configure an MCP client, you define the command it should launch — the MCP server binary — and the client communicates with it over stdio.

What to configure

Most MCP clients ask for the following information:

Field	Description
name	An identifier for the server (for example, `k6`).
command	The program to run. For `k6 x mcp`, this is `k6`. For native installs, `mcp-k6`. For Docker, `docker`.
args	Command-line arguments. For `k6 x mcp`, this is `["x", "mcp"]`. For Docker, include `run`, `--rm`, `-i`, and the image name.
env	Optional environment variables to pass to the server.
transport	Usually `stdio` (some clients assume this by default).

Consult your client’s documentation for the exact configuration file location and format. Look for sections about “MCP servers”, “tool servers”, or “stdio servers”.

Next steps

Learn what your assistant can do once the server is wired up: Tools, prompts, and resources.

Tools, prompts, and resources

Mon, 21 Sep 2026 15:16:28 +0000

Tools, prompts, and resources

The k6 MCP server exposes three kinds of MCP primitives:

Tools: Allow your AI assistant to perform actions, such as validating or running a script.
Prompts: Guided workflows that help you generate scripts or convert existing tests.
Resources: Reference data, which includes docs and type definitions, that your assistant can consult for accurate answers.

These primitives behave identically regardless of how you launch the server — via k6 x mcp, the standalone mcp-k6 binary, or Docker.

Tools

Tools are the core capability of the k6 MCP server. Your AI assistant calls them automatically when it needs to validate code, run a test, or look up documentation.

info

Returns runtime information about the server and local environment:

Server version
Detected k6 version
Login status for Grafana Cloud k6 (via the k6 CLI)

validate_script

Validates a k6 script by running it with minimal load:

1 VU
1 iteration
30s timeout

This validation catches syntax errors, missing imports, missing export default function declarations, and common runtime issues early, before you scale up.

run_script

Runs a k6 script locally with configurable parameters:

vus (default: 1, max: 50)
duration (default: 30s, max: 5m)
iterations (overrides duration if provided)

Returns stdout/stderr, exit code, and (when available) parsed metrics.

list_sections

Lists k6 documentation sections as a depth-limited tree, so your assistant can explore docs without pulling large amounts of content into context.

Parameters include:

version (optional): The k6 version to query. Use all to list all available versions.
category (optional): The documentation category, such as using-k6 or javascript-api.
root_slug (optional): The specific branch to explore.
depth (default: 1, max: 5): The number of levels to include in the tree.

get_documentation

Fetches the full Markdown for a specific documentation section.

Use the slug returned from list_sections.

search_terraform

Searches for Grafana Cloud k6-related resources in the Grafana Terraform provider schema.

Prerequisites:

Terraform installed (terraform on your PATH)
A Terraform project initialized with the Grafana provider (terraform init)

Prompts

Prompts are guided workflows that you invoke explicitly. Unlike tools, which your assistant calls on its own, you trigger a prompt when you want structured help generating or converting a script.

generate_script

Generates a production-ready k6 script from plain-English requirements.

The prompt guides your assistant through:

Researching relevant k6 docs
Applying best practices
Writing the script and validating it

convert_playwright_script

Converts a Playwright test to a k6/browser script.

The prompt guides your assistant through:

Mapping Playwright APIs to k6 equivalents
Applying browser-testing best practices
Validating the converted script

If you set up your editor with k6 x agent, the same workflow is also available as the bundled k6-playwright-converter skill, which activates automatically when you ask your assistant to convert a Playwright test.

How to invoke prompts

The way you invoke a prompt depends on your MCP client:

Client	How to invoke
Claude Code	Type `/mcp__k6__generate_script` or `/mcp__k6__convert_playwright_script` in the chat.
Codex CLI	Type `/mcp` to list available prompts, then invoke by name.
Cursor	Type `/` in chat to open the prompt list and select the prompt.

Note
Prompt support varies by client. If your client doesn’t show prompts, you can describe your goal in chat and your assistant will use the underlying tools directly.

Resources

Resources are reference data your assistant can read to produce accurate, up-to-date answers.

docs://k6/best_practices

A curated best-practices document intended for AI-assisted script authoring.

types://k6/…

k6 TypeScript type definitions, exposed as MCP resources. These help your assistant:

Discover valid import paths
Verify option names and shapes (options, scenario config, thresholds)
Avoid hallucinated APIs when generating scripts

Recommended workflows

Validate, then run

Use this loop for most authoring:

Ask your assistant to validate the script (validate_script).
Fix any issues and repeat until validation passes.
Run the script with a small load (for example, 1–5 VUs) before scaling up.

Explore documentation during authoring

When you need a specific k6 API or option shape:

Your assistant can use list_sections and get_documentation to find authoritative docs.
Type definitions (types://k6/...) confirm exact signatures and option shapes.

Terraform + Grafana Cloud k6 provisioning

If you manage Grafana Cloud k6 resources via Terraform:

Ask your assistant to search for relevant resources with search_terraform.
Review the schema and apply changes in your Terraform project.

Configure your AI assistant on Grafana Labs

Bootstrap your editor with k6 x agent

Bootstrap your editor with k6 x agent

What k6 x agent init does for you

Prerequisites

Quickstart

Supported targets

Bundled skills

Commands

init flags

Example status output

Safety

Troubleshooting

Editors not supported by k6 x agent

How MCP works

What to configure

Next steps

Tools, prompts, and resources

Tools, prompts, and resources

Tools

info

validate_script

run_script

list_sections

get_documentation

search_terraform

Prompts

generate_script

convert_playwright_script

How to invoke prompts

Resources

docs://k6/best_practices

types://k6/…

Recommended workflows

Validate, then run

Explore documentation during authoring

Terraform + Grafana Cloud k6 provisioning

What `k6 x agent init` does for you

`init` flags

Editors not supported by `k6 x agent`