RATL.ai MCP

RATL.ai MCP provides intelligent, workflow-oriented tools for AI-powered test generation and execution. Access 30+ MCP tools for API testing, load testing, and web testing through any MCP-compatible client.

What is RATL.ai MCP?

RATL.ai MCP (Model Context Protocol) server exposes comprehensive testing capabilities as MCP tools that AI assistants can use to:

• Generate API Tests: Automatically create pytest-based functional and E2E tests from your codebase
• Generate Load Tests: Automatically create Gatling-based performance tests
• Generate Web Tests: Automatically analyze URLs and generate web UI test scenarios
• Execute Tests: Run tests on cloud infrastructure and get detailed reports
• Analyze Results: Get AI-powered insights and recommendations

Available Tools

API Test Tools (10 tools):

• Codebase analysis for API testing
• Test plan generation (E2E scenarios + functional tests)
• Pytest code generation
• Test execution and reporting
• Local test result onboarding

Load Test Tools (15 tools):

• Codebase analysis for load testing
• Test plan generation (end-to-end scenarios)
• Gatling code generation
• Load test execution on cloud infrastructure
• Performance analysis and optimization
• Test comparison and benchmarking

Web Test Tools (6 tools):

• Auto-generate test scenarios from URLs
• Review and approve test scenarios
• Execute web tests (webshot)
• Monitor test execution
• Get detailed test reports

Workflows

API Test Workflow:

Codebase Analysis → Test Plan → Code Generation → Validation → Execution → Reports

Load Test Workflow:

Codebase Analysis → Test Plan → Gatling Code → Validation → URL Validation → Execution → Analysis

Web Test Workflow:

Auto-Generate Scenario → Review & Approve → Execute → Monitor → Reports

For complete workflow documentation, see MCP.md.

MCP Server Endpoint

The RATL.ai MCP server is available at:

• Production: https://api.rattlez0.de/public/api/v1/mcp
• Development: http://localhost:8000/api/v1/mcp (if running locally)

Supported MCP Clients

RATL.ai MCP works with any MCP-compatible client:

• Cursor IDE - Native HTTP/SSE support (no bridge needed)
• Claude Desktop - Requires bridge (see setup below)
• Claude API - Native HTTP support
• OpenAI GPT Models - Native HTTP support
• Other MCP Clients - Use HTTP transport if supported, or bridge for stdio-based clients

Quick Start

Step 1: Get Your API Key

1. Visit ril.ratl.ai
2. Navigate to Settings > API Keys
3. Create a new API key or copy an existing one

Step 2: Configure Your MCP Client

Cursor IDE (Native HTTP Support)

1. Open Cursor Settings (Cmd/Ctrl + ,)
2. Navigate to Features > MCP
3. Click + Add New MCP Server
4. Configure:
   • Name: ratl.ai
   • Transport: Streamable HTTP (or SSE)
   • URL: https://api.rattlez0.de/public/api/v1/mcp
   • Headers: Add x-api-key header with your API key
5. Click Save

Claude Desktop (Requires Bridge)

Claude Desktop currently only supports stdio-based MCP servers. Use the bridge to connect:

Install the bridge:

# Option 1: Using npx (Recommended - No Installation)
# Just use npx in configuration (see below)

# Option 2: Install globally
npm install -g @ratl/ratl-mcp

# Option 3: Direct download
# Download index.js from this repository

Configure Claude Desktop:

Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Configuration (using npx - recommended):

{
  "mcpServers": {
    "ratl.ai": {
      "command": "npx",
      "args": [
        "-y",
        "@ratl/ratl-mcp@latest",
        "https://api.rattlez0.de/public/api/v1/mcp",
        "--api-key",
        "YOUR_API_KEY_HERE"
      ]
    }
  }
}

Configuration (using global installation):

{
  "mcpServers": {
    "ratl.ai": {
      "command": "ratl-mcp",
      "args": [
        "https://api.rattlez0.de/public/api/v1/mcp",
        "--api-key",
        "YOUR_API_KEY_HERE"
      ]
    }
  }
}

Configuration (using direct path):

{
  "mcpServers": {
    "ratl.ai": {
      "command": "node",
      "args": [
        "/path/to/mcp-bridge/index.js",
        "https://api.rattlez0.de/public/api/v1/mcp",
        "--api-key",
        "YOUR_API_KEY_HERE"
      ]
    }
  }
}

Restart Claude Desktop after configuration.

Other MCP Clients

For clients that support HTTP-based MCP:

{
  "mcpServers": {
    "ratl.ai": {
      "url": "https://api.rattlez0.de/public/api/v1/mcp",
      "transport": "sse",
      "headers": {
        "x-api-key": "YOUR_API_KEY_HERE"
      }
    }
  }
}

For clients that only support stdio, use the bridge tool (see Claude Desktop setup above).

Example Use Cases

Creating API Tests

You: "Help me create API tests for the OTT API at https://ott.ratl.app"

AI Assistant (using RATL.ai MCP tools):

1. Analyzes your codebase/OpenAPI spec
2. Generates E2E test scenarios and functional test plan
3. Creates pytest test files
4. Validates the code
5. Executes tests and provides reports

Creating Load Tests

You: "Generate load tests for my authentication flow"

AI Assistant (using RATL.ai MCP tools):

1. Analyzes your API endpoints
2. Creates a comprehensive end-to-end load test scenario
3. Generates Gatling Java code
4. Validates code and URL
5. Executes load test on cloud infrastructure
6. Provides performance analysis and recommendations

Creating Web Tests

You: "Test the login page at https://example.com/login"

AI Assistant (using RATL.ai MCP tools):

1. Analyzes the URL and detects page elements (forms, buttons, links)
2. Auto-generates a test scenario with actions and assertions
3. Reviews and approves the generated scenario
4. Executes web test with screenshots and video recording
5. Provides detailed test reports with visual evidence

What You Get

API Testing

• E2E Test Scenarios: User journey tests that test complete workflows
• Functional Tests: Individual endpoint tests with comprehensive coverage
• Automatic Code Generation: AI generates pytest code from your API
• Validation: Automatic code validation before execution (mandatory)
• Detailed Reports: E2E and functional test reports with request/response details
• Size Limit: Total test file contents must be under 50 KB (strictly enforced)
• Local Execution Support: Onboard local test results to track in the platform

Load Testing

• End-to-End Scenarios: Complete user flows tested under load
• Gatling Code Generation: Production-ready Gatling Java code
• Cloud Execution: Tests run on scalable cloud infrastructure
• Performance Metrics: Response times, throughput, error rates
• AI Analysis: Automated insights and optimization recommendations
• URL Validation: Automatic validation of baseUrl before execution (blocks localhost URLs)

Web Testing

• Auto-Generation: Automatically analyzes URLs and generates test scenarios
• Page Analysis: Detects forms, buttons, links, and key UI elements
• Visual Evidence: Screenshots, GIFs, and video recordings of test execution
• Inline Mode: No filesystem access required - perfect for URL-based testing
• Review Workflow: Mandatory review step before execution to ensure quality

Authentication

The MCP server supports multiple authentication methods for flexibility and security:

Authentication Methods (Priority Order)

1. HTTP Header: x-api-key (Recommended for Cursor, Claude, and other HTTP clients)
2. Session Token: x-session-token (Recommended for workflow tools - valid for 1 hour)
3. Parameter: api_key (Backward compatibility - can be passed in tool arguments)

Getting Started

1. Get API Key: From ril.ratl.ai Settings > API Keys
2. Pass in Configuration:
   • For HTTP clients: Include x-api-key header
   • For bridge: Include --api-key YOUR_API_KEY in args
3. Session Tokens (Optional): Initialize with API key to get session token (valid for 1 hour)

Session-Based Authentication (Recommended)

Step 1: Initialize with API key

POST /api/v1/mcp
Headers: x-api-key: your-api-key
Body: {
  "method": "initialize",
  "params": {"api_key": "your-api-key"}
}
Response: {
  "result": {
    "sessionToken": "abc123...",
    "authenticated": true
  }
}

Step 2: Use session token for subsequent calls

POST /api/v1/mcp
Headers: x-session-token: abc123...
Body: {
  "method": "tools/call",
  "params": {...}
}

Benefits:

• ✅ Authenticate once, reuse session token
• ✅ No need to pass API key in every tool call
• ✅ More secure (token expires after 1 hour)
• ✅ Better for workflow automation

Note: Session tokens require Redis for storage. If Redis is unavailable, session creation will fail gracefully, and you can continue using API key authentication directly (via x-api-key header or api_key parameter). The application will not crash if Redis is unavailable - it will simply operate without session support.

Important Requirements

Test Name Parameter (REQUIRED)

All test executions require a descriptive testName parameter:

• Purpose: Provides a meaningful name displayed in the execution dashboard
• Required For:
  • ratl_execute_api_test_suite - API test executions
  • ratl_execute_load_test_suite - Load test executions
  • ratl_execute_web_test - Web test executions
  • ratl_onboard_api_test_local_results - Local test result onboarding
• Examples:
  • API Tests: "E-commerce Platform - User Registration & Checkout", "API Test Suite - 5 E2E scenarios"
  • Load Tests: "Authentication Flow - 100 users/sec", "Payment Gateway - Spike Traffic"
  • Web Tests: "Login Page Test", "Checkout Flow Validation"

Code Validation (MANDATORY)

• API Tests: Code validation is automatic before execution. Execution is blocked if validation fails.
• Load Tests: Code validation is automatic before execution. URL validation also occurs automatically. Execution is blocked if either validation fails.
• Validation Tools: Use ratl_validate_api_test_pytest_code or ratl_validate_load_test_gatling_code to validate code before execution.

URL Validation (Load Tests)

• Automatic: URL validation occurs automatically after code validation passes
• Blocks Localhost: Localhost URLs are blocked (cloud infrastructure cannot reach localhost)
• Tunneling Support: Use tunneling services (ngrok, localtunnel, Cloudflare Tunnel) for local testing
• Guidance Provided: Detailed instructions provided when URL validation blocks execution

Troubleshooting

"command not found: npx" or "command not found: node"

Solution:

• Install Node.js: https://nodejs.org/
• Or use direct path to index.js in configuration

"HTTP 401: Unauthorized"

Solution:

• Verify your API key is correct
• Check API key hasn't expired
• Get a new API key from ril.ratl.ai

Bridge Not Working (Claude Desktop)

Solution:

1. Test bridge manually:

   echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | \
     npx @ratl/ratl-mcp@latest https://api.rattlez0.de/public/api/v1/mcp --api-key YOUR_KEY

2. Check client logs for errors
3. Verify file paths are absolute (not relative)

Tools Not Appearing

Solution:

1. Restart your MCP client after configuration changes
2. Verify API key is correct
3. Check client logs for connection errors
4. For HTTP clients, verify the URL is accessible

Session Token Not Working

Solution:

• Session tokens require Redis. If Redis is unavailable, use API key authentication directly
• Session tokens expire after 1 hour - re-authenticate if needed
• Use x-api-key header as an alternative to session tokens

Bridge Tool (For stdio-based MCP Clients)

The bridge is a technical implementation that enables stdio-based MCP clients (like Claude Desktop) to connect to RATL.ai's HTTP-based MCP server:

1. Client sends JSON-RPC requests via stdin
2. Bridge forwards requests to RATL.ai MCP server over HTTP
3. Bridge receives responses and writes to stdout
4. Client reads responses and processes them

Note: When your MCP client adds native HTTP MCP support, the bridge will no longer be needed.

Bridge Installation

# Install globally
npm install -g @ratl/ratl-mcp

# Or use npx (no installation)
npx @ratl/ratl-mcp@latest <url> [options]

Bridge Command Line Options

ratl-mcp <url> [options]

Options:
  --api-key <key>        API key for authentication (sets x-api-key header)
  --header <name:value>  Additional header (can be used multiple times)
  --transport <type>    Transport type (default: http)

Execution Management

All MCP-executed tests are automatically tracked in the platform:

• Execution Dashboard: View all test executions via REST API endpoints
• Status Tracking: Execution status automatically synced from backend services
• Platform Identification: Executions marked with platform: "MCP" (MCP client-initiated) or platform: "ratl" (frontend rerun)
• Rerun Capability: Execution payloads include full manifest and fileContents for rerunning tests
• Local Execution Onboarding: Track local test executions in the platform using ratl_onboard_api_test_local_results

For more details, see MCP.md section on "MCP Execution Management".

Documentation

• Complete MCP Documentation: See MCP.md for detailed tool documentation, workflows, and examples
• API Documentation: See README.md for REST API documentation
• Website: https://ratl.ai

Support

• Website: https://ratl.ai
• Get API Keys: https://ril.ratl.ai (Settings > API Keys)
• Documentation: MCP.md - Complete MCP server documentation

License

MIT License - See LICENSE file for details.

RATL.ai - Intelligent testing tools powered by AI. Generate, execute, and analyze tests with ease.