xk6-mcp

A k6 extension for testing Model Context Protocol (MCP) servers.

> [!CAUTION]
> This extension is experimental and not officially supported by Grafana Labs.

Installation

1. First, ensure you have xk6 installed:

go install go.k6.io/xk6/cmd/xk6@latest

2. Build a k6 binary with the xk6-mcp extension:

xk6 build --with github.com/dgzlopes/xk6-mcp

3. Import the mcp module in your script, at the top of your test script:

import mcp from 'k6/x/mcp';

4. The built binary will be in your current directory. You can move it to your PATH or use it directly:

./k6 run script.js

Example

> ⚠️ This example depends on mcp-example-server
> You can download the latest version from the releases page.

import mcp from 'k6/x/mcp';
export default function () {

  // Initialize MCP Client with stdio transport

  const client = new mcp.StdioClient({

    path: './mcp-example-server',

  });
// Check connection to MCP server

  console.log('MCP server running:', client.ping());
// List all available tools

  console.log('Tools available:');

  const tools = client.listAllTools().tools;

  tools.forEach(tool => console.log(  - ${tool.name}));
// List all available resources

  console.log('Resources available:');

  const resources = client.listAllResources().resources;

  resources.forEach(resource => console.log(  - ${resource.uri}));
// List all available prompts

  console.log('Prompts available:');

  const prompts = client.listAllPrompts().prompts;

  prompts.forEach(prompt => console.log(  - ${prompt.name}));
// Call a sample tool

  const toolResult = client.callTool({ name: 'greet', arguments: { name: 'Grafana k6' } });

  console.log(Greet tool response: "${toolResult.content[0].text}");
// Read a sample resource

  const resourceContent = client.readResource({ uri: 'embedded:info' });

  console.log(Resource content: ${resourceContent.contents[0].text});
// Get a sample prompt

  const prompt = client.getPrompt({ name: 'greet' });

  console.log(Prompt: ${prompt.messages[0].content.text});

}

F.A.Q.

What about non-stdio transports?

Both SSE and Streamable HTTP are supported too!

You can use them like this:

// SSE
const client = new mcp.SSEClient({
    base_url: 'http://localhost:3002',
});
// Streamable HTTP

const client = new mcp.StreamableHTTPClient({

    base_url: 'http://localhost:3001',

});

What about pagination?

The extension offers two ways to list resources, tools, and prompts:

// With All: Handles pagination automatically
const allTools = client.listAllTools();
const allResources = client.listAllResources();
const allPrompts = client.listAllPrompts();
// Without All: Requires manual pagination

const first = client.listTools()

const second = client.listTools({ cursor: first.next_cursor });

What about metrics?

The extension automatically tracks RED-style metrics for every MCP operation:

- mcp_request_duration (trend): Duration of each MCP request (in milliseconds).
- mcp_request_count (counter): Number of MCP requests made.
- mcp_request_errors (counter): Number of failed MCP requests.

Each metric is tagged wit:
- method: The MCP method called (e.g., GetPrompt, ListTools).