MCP Testing Framework
📚 Documentation | 📦 | 🐛 | 💬
Power your agent
Install from the publisher. Not a PlugMCP endpoint.
Host a copy with our keys and logs.
No packaged release in the registry yet. Follow the repository README.
Remote URL or a command on your machine? How the two installs differ
Run on PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
LaunchFrom the publisher
📚 Documentation | 📦 | 🐛 | 💬
A production-grade Java testing framework for Model Context Protocol (MCP) servers with type-safe APIs, fluent assertions, and comprehensive monitoring.
A production-grade Java testing framework for Model Context Protocol (MCP) servers with type-safe APIs, fluent assertions, and comprehensive monitoring.
Add to your pom.xml:
<dependency>
<groupId>io.github.abhiramrathod</groupId>
<artifactId>mcp-test-api</artifactId>
<version>1.5.2</version>
<scope>test</scope>
</dependency>
Or Gradle:
testImplementation 'io.github.abhiramrathod:mcp-test-api:1.5.2'
Note: Only add
mcp-test-api- all other modules are included transitively.
import mcp.toolkit.testing.framework.api.*;
import mcp.toolkit.testing.framework.api.model.*;
public class MyMcpTest {
@Test
public void testMcpServer() {
// Connect to MCP server
McpClient client = McpClient.connectTo("http://localhost:8080")
.config(McpClientConfig.builder()
.timeout(Duration.ofSeconds(30))
.build())
.initializeOnBuild()
.build();
// Test tool invocation
McpToolResult result = client.tools()
.callTool("calculator", Map.of("operation", "add", "a", 5, "b", 3))
.assertSuccess()
.assertTextContains("8");
// Verify performance
client.exchanges().assertAverageLatencyBelow(McpMethod.TOOLS_CALL, 500);
client.close();
}
}
Full Documentation: https://testmcp.pages.dev/]
MCP client configuration is available via McpClientConfig. Key options:
timeout (Duration) — request timeout applied to connections and RPC calls. Default: 10 seconds (McpClientConfig.DEFAULT_TIMEOUT).protocolVersion (String) — MCP protocol version the client speaks. Default: 2024-11-05 (legacy session era, backward compatible; McpClientConfig.DEFAULT_PROTOCOL_VERSION). Use 2026-07-28 for the stateless protocol — no initialize handshake, version negotiation via server/discover, results carry resultType/ttlMs/cacheScope, and change notifications flow over subscriptions/listen./sse (McpClientConfig.DEFAULT_SSE_PATH).proxy (java.net.Proxy) — optional HTTP proxy for transport connections. Omit (or null) for a direct connection. Only Proxy.Type.HTTP is supported; other types throw IllegalArgumentException.Create a config with the fluent builder:
McpClientConfig config = McpClientConfig.builder()
.timeout(Duration.ofSeconds(30))
.protocolVersion("2024-11-05")
.build();
Pass it to the client with .config(config) when building the McpClient.
By default the client uses SSE (Server-Sent Events) transport. For servers that support it, you can use Streamable HTTP transport which sends each request as a standalone HTTP POST without a persistent SSE connection:
McpClient client = McpClient.connectTo("http://localhost:8080")
.streamableHttp()
.build();
To use a custom endpoint path (default: /mcp):
McpClient client = McpClient.connectTo("http://localhost:8080")
.streamableHttp("/api/mcp")
.build();
For environments behind an HTTP proxy (e.g. a corporate network), both transports can route through a proxy via McpClientConfig.proxy(...):
Proxy httpProxy = new Proxy(Proxy.Type.HTTP, new InetSocketAddress("proxy.corp.example", 8080));
McpClientConfig config = McpClientConfig.builder()
.proxy(httpProxy)
.build();
McpClient client = McpClient.connectTo("http://mcp-server.internal:8080")
.config(config)
.build();
Proxy.Type.HTTP is accepted — SOCKS and NO_PROXY throw IllegalArgumentException.proxy is omitted or null, both transports connect directly (the default behavior).http:// targets and CONNECT for https://.null proxy the JDK transport falls back to the JVM default ProxySelector (honoring -Dhttp.proxyHost=... / -Dhttps.proxyHost=... system properties), while the Netty transport always connects directly unless a proxy is set.Build the multi-module project with Maven (from repo root):
mvn -T 1C clean install
Run tests for examples module (example tests use JUnit 5):
mvn -pl mcp-test-examples test
Generate Javadocs (the build is configured to attach javadocs during release builds):
mvn javadoc:jar
Publishing notes:
distributionManagement entry for GitHub Packages in pom.xml; builds on CI may be configured to publish artifacts to GitHub Packages or other registries (JitPack is also a common distribution option). See CI workflow for publishing configuration.List<McpTool> tools = client.tools().listTools();
McpToolResult result = client.tools().callTool("my-tool", args).assertSuccess();
List<McpResource> resources = client.resources().listResources();
McpResourceContent content = client.resources().readResource("file://data.txt");
List<McpPrompt> prompts = client.prompts().listPrompts();
McpPromptResult prompt = client.prompts().getPrompt("translate", args);
client.exchanges().assertAverageLatencyBelow(McpMethod.TOOLS_CALL, 500);
long p99 = client.exchanges().latencyPercentile(McpMethod.TOOLS_CALL, 99);
mcp-test-api (Public)
└── mcp-test-client (Internal)
└── mcp-test-transport (SSE / Streamable HTTP)
├── mcp-test-interfaces
└── mcp-test-core
Design Principle: Users only import mcp-test-api. All internal modules are abstracted away.
Check out complete examples in the mcp-test-examples module:
Contributions are welcome! Please feel free to submit a Pull Request.
git checkout -b feature/amazing-feature)git commit -m 'Add amazing feature')git push origin feature/amazing-feature)Licensed under the Apache License 2.0.
Built with ❤️ for the developer community
A production-grade Java testing framework for Model Context Protocol (MCP) servers with type-safe APIs, fluent assertions, and comprehensive monitoring.
Tools
No tool list yet. Remote servers get one after the first health check.
FAQ
Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.
No required environment variable is listed on this record.
MCP Server Testing runs locally over stdio.
Last checked 2026-10-26. A production-grade Java testing framework for Model Context Protocol (MCP) servers with type-safe APIs, fluent assertions, and comprehensive monitoring.