mcpengine/infra/factory-tools/mcp-validator/mcp_testing/http/README.md

MCP HTTP Server Testing Module

This module provides comprehensive testing capabilities for MCP HTTP server implementations, focusing on strict compliance with the official MCP specification.

Testing Philosophy

This test suite follows the principle of testing only what is explicitly specified in the official MCP specification at https://modelcontextprotocol.io. We do not test implementation details or "best practices" that are not mandated by the specification.

Features

• Specification-Only Testing: Tests only behaviors explicitly required by the MCP specification
• Protocol Version Support: Tests compatibility with MCP protocol versions 2024-11-05, 2025-03-26, and 2025-06-18
• OAuth 2.1 Authentication: Comprehensive testing of OAuth 2.1 flows per the 2025-06-18 specification
• HTTP Transport Compliance: Validates proper HTTP transport implementation
• Session Management: Tests session handling where specified
• Tool and Resource Testing: Dynamic testing of available tools and resources
• Error Handling: Tests proper JSON-RPC error responses

Quick Start

from mcp_testing.http.tester import MCPHttpTester

# Initialize tester
tester = MCPHttpTester("http://localhost:8080", debug=True)

# Run comprehensive test suite
result = tester.run_comprehensive_tests()

Test Categories

Core Protocol Tests

• Initialization: Server initialization and capability negotiation
• Session Management: Session handling (where specified)
• Tool Operations: Tool listing and execution
• Protocol Version Negotiation: Multi-version compatibility

HTTP Transport Tests

• Status Codes: Tests only specified HTTP behaviors (invalid JSON, missing method)
• Headers: Required header validation
• CORS: OPTIONS request handling

OAuth 2.1 Authentication Tests (2025-06-18)

• Authorization Code Flow: PKCE-enabled OAuth flow
• Token Management: Token validation and refresh
• Error Scenarios: Proper OAuth error handling
• WWW-Authenticate Headers: Compliance with authentication requirements

Protocol-Specific Features

• 2025-06-18: Structured tool output, batch request rejection, elicitation support
• 2025-03-26: Async tool support
• 2024-11-05: Basic protocol compliance

Example Test Output

=== MCP HTTP Server Comprehensive Test Suite ===
Protocol Version: 2025-06-18

Testing OAuth 2.1 authorization flow...
✅ Authorization code flow supported
✅ PKCE S256 method supported
✅ Token exchange flow validated

=== Testing HTTP Status Codes (MCP Specification Only) ===
✅ invalid_json: Got expected status code 400
    Invalid JSON should return 400 (HTTP standard)
✅ missing_method: Got expected status code 400
    Missing method field should return 400 (JSON-RPC requirement)

Note: Tests for unknown_method and invalid_session have been removed
because they test unspecified HTTP implementation details, not MCP specification compliance.

=== Testing HTTP Headers ===
✅ content_type: All required headers present and valid
✅ session_id_present: All required headers present and valid
✅ protocol_version: All required headers present and valid

=== Testing Protocol Version Negotiation ===
✅ Version 2024-11-05: Successfully negotiated (server: 2024-11-05)
✅ Version 2025-03-26: Successfully negotiated (server: 2025-03-26)
✅ Version 2025-06-18: Successfully negotiated (server: 2025-06-18)

🎉 SERVER IS FULLY COMPLIANT WITH MCP SPECIFICATION
   All core functionality and protocol-specific features validated
   ✅ OAuth 2.1 authentication flow validated
   ✅ WWW-Authenticate header handling compliant
   ✅ MCP 2025-06-18 specific features validated

Removed Tests

The following tests have been intentionally removed because they test unspecified implementation details:

• unknown_method: The MCP specification does not mandate specific HTTP status codes for unknown JSON-RPC methods
• invalid_session: Session validation behavior is not clearly specified in the MCP protocol

This aligns with our philosophy of testing only what is explicitly specified in the official MCP documentation.

Configuration

Basic Configuration

tester = MCPHttpTester("http://localhost:8080", debug=True)

Protocol Version Testing

# Test specific protocol version
tester.protocol_version = "2025-06-18"
result = tester.run_comprehensive_tests()

API Reference

MCPHttpTester Class

Main testing class for MCP HTTP server validation.

Methods

• run_comprehensive_tests(): Execute full test suite
• initialize(): Test server initialization
• list_tools(): Test tool listing
• test_available_tools(): Test all available tools
• test_oauth_flow(): Test OAuth 2.1 authentication
• test_status_codes(): Test HTTP status code handling
• test_headers(): Test HTTP header compliance
• test_protocol_versions(): Test version negotiation

Contributing

When adding new tests, ensure they test only behaviors explicitly specified in the MCP specification. Do not add tests for:

• Implementation-specific HTTP status codes
• Unspecified error handling behavior
• Custom extensions or "best practices"

All tests should reference the specific section of the MCP specification they validate.