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

# Testing & Debugging

> How to test and debug your MCP servers effectively

# Testing & Debugging Your MCP Server

Testing MCP servers is different from testing regular APIs. You need to verify that AI agents can understand and use your tools correctly, not just that the tools work in isolation.

## Why Testing Matters

**Regular API testing:** Does the function work?\
**MCP testing:** Can AI agents use the function correctly?

AI agents can fail in ways humans don't:

* Pick the wrong tool for the task
* Miss required parameters
* Misunderstand tool descriptions
* Get confused by similar tools

## Testing Strategy Overview

<Steps>
  <Step title="Platform Testing">
    Use the built-in test button in our platform
  </Step>

  <Step title="MCP Playground">
    Comprehensive testing with our open-source tool
  </Step>

  <Step title="Protocol Validation">
    Ensure MCP compliance with official tools
  </Step>

  <Step title="AI Integration">
    Test with real AI clients (final step)
  </Step>
</Steps>

## Method 1: Platform Built-in Testing

**Best for**: Quick validation during development

Our platform includes integrated testing functionality accessible directly from the MCP builder interface.

### How to Use

1. **Build your MCP** using the platform interface
2. **Click the "Test" button** in the interface
3. **Review sandbox results** for any build errors
4. **Fix issues** by prompting the AI with corrections
5. **Re-test** until all checks pass

### What It Tests

* **Build process** - Does your MCP compile correctly?
* **Dependencies** - Are all required packages available?
* **Configuration** - Is your MCP properly configured?
* **AI interaction** - Limited AI behavior testing

<Warning>
  Platform testing validates the build process but doesn't test how AI agents interact with your MCP. Use additional methods for comprehensive testing.
</Warning>

## Method 2: MCP Playground (Recommended)

**Best for**: Comprehensive development testing

Our open-source MCP Playground provides the most thorough testing environment for MCP development.

### Setup

1. **Repository**: [https://github.com/rosaboyle/mcp-playground](https://github.com/rosaboyle/mcp-playground)
2. **Installation**: Clone and follow setup instructions
3. **Connect**: Add your deployed MCP server URL
4. **Test**: Interactive interface for comprehensive testing

### Testing Features

<CardGroup cols={2}>
  <Card title="Tool Testing" icon="wrench">
    Test individual tools with custom parameters
  </Card>

  <Card title="Resource Testing" icon="database">
    Verify resource accessibility and data format
  </Card>

  <Card title="Error Simulation" icon="exclamation-triangle">
    Test error handling with invalid inputs
  </Card>

  <Card title="Performance Monitoring" icon="stopwatch">
    Track response times and identify bottlenecks
  </Card>
</CardGroup>

### What to Test

**Start with simple tests:**

* Can AI discover available tools?
* Do basic tools execute successfully?
* Are required parameters validated?
* Do error messages make sense?

**Then test edge cases:**

* Invalid parameter values
* Missing required parameters
* Network timeouts
* Large data payloads

## Method 3: Protocol Validation

**Best for**: Ensuring MCP standard compliance

Use official MCP validation tools to ensure your server follows the protocol correctly.

### MCP Inspector

Anthropic provides official tools for protocol validation:

1. **Access**: Check [Anthropic's documentation](https://docs.anthropic.com/claude/docs/mcp) for latest tools
2. **Install**: Follow official installation instructions
3. **Validate**: Run compliance checks against your server
4. **Fix**: Address any protocol violations identified

### What Gets Validated

* MCP protocol version compatibility
* Tool and resource schema compliance
* Error response formatting
* Connection stability
* Message format correctness

## Method 4: AI Integration Testing

**Best for**: Real-world usage validation

<Warning>
  Only use this method after your MCP passes all previous testing methods. This should be your final validation step.
</Warning>

### When to Use AI Testing

Only test with AI clients when:

* **Platform testing passes**
* **MCP Playground testing succeeds**
* **Protocol validation passes**
* **You're ready for real user scenarios**

### Recommended AI Clients

<CardGroup cols={3}>
  <Card title="Claude Desktop" icon="robot">
    Anthropic's official client
  </Card>

  <Card title="Cursor" icon="code">
    AI-powered code editor
  </Card>

  <Card title="Windsurf" icon="wind">
    AI development environment
  </Card>
</CardGroup>

### AI Testing Process

1. **Connect** your deployed MCP server to the AI client
2. **Create test scenarios** that should trigger your tools
3. **Monitor AI behavior** - does it select the right tools?
4. **Verify responses** - are they what you expected?
5. **Identify confusion points** - where does the AI struggle?

## Common Issues & Solutions

<AccordionGroup>
  <Accordion title="Tools not executing">
    **Symptoms**: Tools appear available but fail when called

    **Debugging steps**:

    * Check server logs for execution errors
    * Verify all dependencies are installed
    * Test tool execution manually in MCP Playground
    * Review parameter validation logic

    **Common causes**:

    * Missing environment variables
    * Incorrect file paths
    * Database connection issues
    * Permission problems
  </Accordion>

  <Accordion title="AI selects wrong tools">
    **Symptoms**: AI consistently picks similar but incorrect tools

    **Debugging steps**:

    * Review tool names and descriptions
    * Make tool purposes more distinct
    * Simplify tool selection options
    * Add clear examples to tool descriptions

    **Solutions**:

    * Rename similar tools to be more specific
    * Improve tool descriptions with clear use cases
    * Reduce the number of similar tools
    * Add parameter examples
  </Accordion>

  <Accordion title="Missing parameters">
    **Symptoms**: AI calls tools without required parameters

    **Debugging steps**:

    * Check parameter schema definitions
    * Verify required fields are marked correctly
    * Review parameter descriptions
    * Test with MCP Playground parameter validation

    **Solutions**:

    * Simplify parameter requirements
    * Provide clear parameter descriptions
    * Add parameter examples
    * Implement better validation messages
  </Accordion>

  <Accordion title="Slow response times">
    **Symptoms**: Long delays between AI requests and tool responses

    **Debugging steps**:

    * Use MCP Playground performance monitoring
    * Check server resource usage
    * Review database query performance
    * Monitor network latency

    **Solutions**:

    * Optimize database queries
    * Add caching where appropriate
    * Reduce external API calls
    * Improve server resources
  </Accordion>
</AccordionGroup>

## Debugging Checklist

Before deploying to production, ensure your MCP server passes all these checks:

### **Platform Testing**

* [ ] Build process completes successfully
* [ ] No compilation errors
* [ ] All dependencies resolve correctly
* [ ] Configuration is valid

### **Functional Testing**

* [ ] All tools execute successfully with valid inputs
* [ ] All resources return expected data formats
* [ ] Error handling works for invalid inputs
* [ ] Parameter validation catches errors

### **Protocol Compliance**

* [ ] MCP Inspector validation passes
* [ ] All tool schemas are valid
* [ ] Error responses follow MCP format
* [ ] Connection handling is stable

### **AI Integration**

* [ ] AI can discover and list tools
* [ ] AI selects appropriate tools for requests
* [ ] AI provides required parameters
* [ ] End-to-end workflows complete successfully

### **Performance**

* [ ] Response times meet requirements
* [ ] Server handles expected load
* [ ] Error rates are acceptable
* [ ] Resource usage is reasonable

## Testing Best Practices

### 1. Test Early and Often

Don't wait until your MCP is "complete" to start testing:

* **After each tool**: Test individual tools as you build them
* **After major changes**: Re-run your test suite
* **Before deployment**: Complete validation workflow

### 2. Create Realistic Test Scenarios

Test with scenarios your users will actually encounter:

```text theme={null}
// Good test scenarios
"Help me send an email to John about the meeting tomorrow"
"Show me my calendar for next week"
"Create a task to review the quarterly report"

// Poor test scenarios  
"Execute function X with parameter Y"
"Call tool Z"
"Test the API"
```

### 3. Document Your Tests

Keep track of:

* Test scenarios that work well
* Common failure patterns
* Performance benchmarks
* AI behavior observations

### 4. Monitor Production Usage

After deployment:

* Track tool usage patterns
* Monitor error rates
* Collect user feedback
* Watch for unexpected AI behavior

## Next Steps

<CardGroup cols={2}>
  <Card title="Deploy Your MCP" icon="rocket" href="/quickstart#step-4-deploy-your-server">
    Ready to deploy your tested MCP server
  </Card>

  <Card title="Monitor Performance" icon="chart-line" href="/my-deployments">
    Track your deployed MCPs in production
  </Card>

  <Card title="MCP Playground" icon="play" href="https://github.com/rosaboyle/mcp-playground">
    Get our comprehensive testing tool
  </Card>

  <Card title="Best Practices" icon="star" href="/building/best-practices">
    Learn how to build better MCP servers
  </Card>
</CardGroup>

## Remember

**Testing MCPs is about validating the AI-tool interaction, not just the tools themselves.**

A perfectly working tool that AI agents can't use correctly is worse than no tool at all. Always prioritize testing how AI agents actually interact with your MCP server.