> ## 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.

# Test MCP Server

> Test your MCP server with AI agents

Test how AI agents interact with your MCP server.

## Request

<ParamField body="mcp_id" type="string" required>
  ID of the MCP server to test
</ParamField>

<ParamField body="message" type="string" required>
  Message to send to the AI agent
</ParamField>

<ParamField body="ai_model" type="string">
  AI model to use for testing. Options: `claude-sonnet-4-5`, `gpt-5.2`, `gpt-5.2`
  Default: `claude-sonnet-4-5`
</ParamField>

<ParamField body="context" type="object">
  Additional context for the AI agent

  <Expandable title="Context Object">
    <ParamField body="user_id" type="string">
      User ID for resource access
    </ParamField>

    <ParamField body="session_data" type="object">
      Session-specific data
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Whether the test completed successfully
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="Test Results">
    <ResponseField name="ai_response" type="string">
      The AI agent's response
    </ResponseField>

    <ResponseField name="tools_used" type="array">
      List of tools the AI called
    </ResponseField>

    <ResponseField name="resources_accessed" type="array">
      List of resources the AI accessed
    </ResponseField>

    <ResponseField name="execution_time" type="number">
      Test execution time in seconds
    </ResponseField>

    <ResponseField name="success_rate" type="number">
      Success rate of tool calls (0-1)
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash Example Request theme={null}
  curl -X POST https://api.leanmcp.com/v1/test \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "mcp_id": "mcp_abc123def456",
      "message": "Send an email to john@example.com saying hello",
      "ai_model": "claude-sonnet-4-5",
      "context": {
        "user_id": "user_123"
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "success": true,
    "data": {
      "ai_response": "I've sent an email to john@example.com with the subject 'Hello' and a friendly greeting message.",
      "tools_used": ["send_email"],
      "resources_accessed": ["user://contacts"],
      "execution_time": 2.3,
      "success_rate": 1.0
    },
    "meta": {
      "request_id": "req_test_789",
      "timestamp": "2023-12-01T12:00:00Z"
    }
  }
  ```
</ResponseExample>

## Testing Best Practices

### Start Simple

Test basic tool usage first:

```json theme={null}
{
  "mcp_id": "your-mcp-id",
  "message": "What tools do you have available?",
  "ai_model": "claude-sonnet-4-5"
}
```

### Test Edge Cases

Try confusing or ambiguous requests:

```json theme={null}
{
  "mcp_id": "your-mcp-id", 
  "message": "Do that thing with the data",
  "ai_model": "claude-sonnet-4-5"
}
```

### Test Complex Workflows

Chain multiple tool calls together:

```json theme={null}
{
  "mcp_id": "your-mcp-id",
  "message": "Check my contacts, find John's email, and send him a meeting invite for tomorrow at 2pm",
  "ai_model": "claude-sonnet-4-5"
}
```

## Interpreting Results

### Success Rate

* **1.0**: All tool calls worked perfectly
* **0.8-0.9**: Mostly successful, minor issues
* **0.5-0.7**: Some failures, needs improvement
* **\< 0.5**: Major issues, review tool descriptions

### Common Issues

* **Wrong tools used**: Tool descriptions too similar
* **Missing tools**: AI needs tools that don't exist
* **Failed calls**: Input validation or execution errors
* **No tools used**: AI didn't understand the request