> ## Documentation Index
> Fetch the complete documentation index at: https://docs.golf.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Compliance testing

> Validate that your MCP server correctly implements the Model Context Protocol specification

## What is Compliance Testing?

Compliance testing verifies that your MCP server adheres to the MCP protocol specification. It checks handshake procedures, capability negotiations, tool definitions, and error handling patterns to ensure your server works correctly with any MCP client.

### Key Benefits

* **Protocol conformance** - Ensure your server follows MCP standards
* **Interoperability** - Verify compatibility with different MCP clients
* **Specification coverage** - Test all required protocol features
* **Error handling validation** - Check proper error responses and edge cases

## How It Works

```mermaid theme={null}
graph TD
    A[Compliance Test Start] --> B[Protocol Handshake]
    B --> C[Capability Discovery]
    C --> D[Tool Enumeration]
    D --> E[Resource Validation]
    E --> F[Error Handling Check]
    F --> G[Protocol Version Check]
    G --> H[Compliance Report]
```

## Configuration

### Basic Compliance Test

```json theme={null}
{
  "suite_id": "mcp_compliance_check",
  "name": "MCP Protocol Compliance",
  "suite_type": "compliance",
  "strict_mode": true,
  "test_cases": [
    {
      "protocol_version": "2025-06-18",
      "check_categories": ["handshake", "capabilities", "tools"],
      "required_capabilities": ["tools", "resources"]
    }
  ]
}
```

### Test Configuration Fields

| Field                  | Type   | Default                                              | Description                                |
| ---------------------- | ------ | ---------------------------------------------------- | ------------------------------------------ |
| protocol\_version      | string | "2025-06-18"                                         | MCP protocol version to validate against   |
| check\_categories      | array  | \["handshake", "capabilities", "tools", "resources"] | Categories of compliance checks to run     |
| required\_capabilities | array  | \[]                                                  | Specific capabilities that must be present |

### Suite-Level Settings

| Setting      | Type    | Default | Description                        |
| ------------ | ------- | ------- | ---------------------------------- |
| strict\_mode | boolean | true    | Enforce strict protocol compliance |

## Check Categories

### 1. Handshake Testing (`"handshake"`)

Validates the MCP connection establishment:

```json theme={null}
{
  "check_categories": ["handshake"],
  "protocol_version": "2025-06-18"
}
```

**Verifies:**

* Proper initialization sequence
* Protocol version negotiation
* Client/server capability exchange
* Error handling during setup

### 2. Capability Discovery (`"capabilities"`)

Tests capability advertisement and validation:

```json theme={null}
{
  "check_categories": ["capabilities"],
  "required_capabilities": ["tools", "resources", "prompts"]
}
```

**Verifies:**

* All advertised capabilities are functional
* Required capabilities are present
* Capability metadata is properly formatted
* Dynamic capability updates work correctly

### 3. Tool Validation (`"tools"`)

Comprehensive tool testing:

```json theme={null}
{
  "check_categories": ["tools"],
  "required_capabilities": ["tools"]
}
```

**Verifies:**

* All declared tools can be invoked
* Tool schemas match actual parameters
* Tool responses follow expected formats
* Error handling for invalid tool calls

### 4. Resource Testing (`"resources"`)

Resource access and management:

```json theme={null}
{
  "check_categories": ["resources"],
  "required_capabilities": ["resources"]
}
```

**Verifies:**

* Resource enumeration works correctly
* Resource content can be retrieved
* Permission handling is implemented
* Resource URIs are properly formatted

### 5. Advanced Features (`"advanced"`)

Advanced MCP protocol features:

```json theme={null}
{
  "check_categories": ["advanced"]
}
```

**Verifies:**

* Sampling support (server requesting LLM completions)
* Elicitation support (server requesting user input)
* Notification support
* Error handling for edge cases

## Strict vs Permissive Mode

### Strict Mode (`"strict_mode": true`)

* Enforces exact specification compliance
* Fails on any protocol deviations
* Requires all standard capabilities
* Validates message format precisely

**Use when:**

* Building production MCP servers
* Need guaranteed interoperability
* Preparing for deployment
* Testing against reference implementations

### Permissive Mode (`"strict_mode": false`)

* Allows minor protocol variations
* Warns but doesn't fail on non-critical issues
* Accepts partial capability implementations
* More forgiving of format variations

**Use when:**

* Developing and debugging servers
* Testing experimental features
* Working with legacy implementations
* Gradual migration to full compliance

## Protocol Version Testing

### Current Version Compliance

```json theme={null}
{
  "protocol_version": "2025-06-18",
  "check_categories": ["handshake", "capabilities", "tools", "resources"],
  "strict_mode": true
}
```

### Version-Specific Checks

Different protocol versions may have different requirements:

```json theme={null}
{
  "suite_type": "compliance",
  "test_cases": [
    {
      "protocol_version": "2024-11-05",
      "check_categories": ["handshake", "tools"]
    },
    {
      "protocol_version": "2025-06-18",
      "check_categories": ["handshake", "tools", "resources", "streaming"]
    }
  ]
}
```

## Example Compliance Configurations

### Basic Server Validation

```json theme={null}
{
  "suite_id": "basic_compliance",
  "name": "Essential MCP Compliance",
  "suite_type": "compliance",
  "strict_mode": false,
  "test_cases": [
    {
      "protocol_version": "2025-06-18",
      "check_categories": ["handshake", "capabilities"],
      "required_capabilities": ["tools"]
    }
  ]
}
```

### Comprehensive Testing

```json theme={null}
{
  "suite_id": "full_compliance",
  "name": "Complete MCP Protocol Validation",
  "suite_type": "compliance",
  "strict_mode": true,
  "test_cases": [
    {
      "protocol_version": "2025-06-18",
      "check_categories": ["handshake", "capabilities", "tools", "resources"],
      "required_capabilities": ["tools", "resources", "prompts"]
    }
  ]
}
```

### Production Readiness

```json theme={null}
{
  "suite_id": "production_compliance",
  "name": "Production MCP Server Validation",
  "suite_type": "compliance",
  "strict_mode": true,
  "test_cases": [
    {
      "protocol_version": "2025-06-18",
      "check_categories": ["handshake", "capabilities", "tools", "resources", "advanced"],
      "required_capabilities": ["tools", "resources"],
      "metadata": {
        "environment": "production",
        "criticality": "high"
      }
    }
  ]
}
```

## Server Configuration

### Server Config Format

```json theme={null}
{
  "url": "https://your-mcp-server.com/mcp",
  "name": "server_name"
}
```

Note: The `type` field was removed from server configurations for simplicity.

## Running Compliance Tests

### With Test Suites (Recommended)

```bash theme={null}
# Create compliance test suite
mcp-t create suite

# Select "compliance" when prompted for suite type

# Run compliance tests
mcp-t run compliance-suite-id server-id --verbose
```

## Next Steps

1. **[Run your first compliance test](../cli-reference.md)**
2. **[Learn about security testing](security.md)** for auth validation
3. **[Explore conversational testing](conversational.md)** for user experience
4. **[Understand server configuration](../concepts/servers.md)** for proper setup