> ## Documentation Index
> Fetch the complete documentation index at: https://mcp-eval.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Building with Claude

> Use Claude subagents to accelerate mcp-eval test development with specialized AI assistants

mcp-eval includes specialized Claude subagents that help you write, debug, and optimize tests. These subagents are AI assistants with deep knowledge of mcp-eval patterns and best practices.

## Available Subagents

mcp-eval ships with several specialized subagents in [`src/mcp_eval/data/subagents/`](https://github.com/lastmile-ai/mcp-eval/tree/main/src/mcp_eval/data/subagents). You can view and copy the complete definitions below. Save these as `.md` files in your `.claude/agents` directory:

<Tabs>
  <Tab title="Core Subagents">
    ### Test Writer

    View the complete [MCP-Eval Test Writer](/subagents/mcp-eval-test-writer) subagent definition.

    Expert at writing comprehensive mcp-eval tests in all styles (decorator, pytest, dataset).

    ### Test Generator

    View the complete [MCP-Eval Test Generator](/subagents/mcp-eval-test-generator) subagent definition.

    Generates complete test suites with diverse scenarios and comprehensive coverage.

    ### Debugger

    View the complete [MCP-Eval Debugger](/subagents/mcp-eval-debugger) subagent definition.

    Expert at debugging test failures, analyzing OTEL traces, and troubleshooting configuration issues.

    ### Config Expert

    View the complete [MCP-Eval Config Expert](/subagents/mcp-eval-config-expert) subagent definition.

    Expert at configuring mcp-eval and managing mcpeval.yaml files for optimal performance.
  </Tab>

  <Tab title="Test Generation Pipeline">
    ### Scenario Designer

    View the complete [Test Scenario Designer](/subagents/test-scenario-designer) subagent definition.

    Creates diverse, high-quality test scenarios for MCP servers (Step 1 of generation pipeline).

    ### Assertion Refiner

    View the complete [Test Assertion Refiner](/subagents/test-assertion-refiner) subagent definition.

    Refines and enhances test assertions for comprehensive coverage (Step 2 of generation pipeline).

    ### Code Emitter

    View the complete [Test Code Emitter](/subagents/test-code-emitter) subagent definition.

    Converts test scenarios into valid Python test code with proper syntax (Step 3 of generation pipeline).
  </Tab>
</Tabs>

## Setup

<Tabs>
  <Tab title="Option 1: Copy to Project">
    For Claude Code:

    ```bash theme={null}
    mkdir -p .claude/agents
    cp path/to/mcp_eval/data/subagents/*.md .claude/agents/
    ```
  </Tab>

  <Tab title="Option 2: Reference from Package">
    Find your package location:

    ```bash theme={null}
    python -c "import mcp_eval, os; print(os.path.join(os.path.dirname(mcp_eval.__file__), 'data', 'subagents'))"
    ```

    Add to your `mcpeval.yaml`:

    ```yaml theme={null}
    agents:
      enabled: true
      search_paths:
        # Add the path from the command above
        - "/path/to/site-packages/mcp_eval/data/subagents"
        # Standard locations
        - ".claude/agents"
        - "~/.claude/agents"
      pattern: "*.md"
    ```
  </Tab>

  <Tab title="Option 3: Development Mode">
    If running from source:

    ```yaml theme={null}
    agents:
      enabled: true
      search_paths:
        - "./src/mcp_eval/data/subagents"  # See: https://github.com/lastmile-ai/mcp-eval/tree/main/src/mcp_eval/data/subagents
      pattern: "*.md"
    ```
  </Tab>
</Tabs>

## Using Subagents in Claude Code

Once configured, Claude Code will automatically discover and use these subagents when appropriate. You can also explicitly request them:

### Writing Tests

```
"Use the mcp-eval-test-writer subagent to create comprehensive tests for my fetch server"
```

### Debugging Failures

```
"Use the mcp-eval-debugger subagent to help me understand why my tests are failing"
```

### Configuration Help

```
"Use the mcp-eval-config-expert subagent to set up my mcpeval.yaml correctly"
```

## Using Subagents for Test Generation

The test generation subagents work together to create high-quality tests:

1. **test-scenario-designer** - Designs comprehensive test scenarios
2. **test-assertion-refiner** - Enhances assertions for better coverage
3. **test-code-emitter** - Generates syntactically correct Python code

These can be used manually or integrated into the `mcp-eval generate` workflow.

## Subagent Examples

### Test Writer Example

The `mcp-eval-test-writer` subagent can help create tests in any style:

```python theme={null}
# Decorator style
@task("Fetch and validate")
async def test_fetch_validate(agent: Agent, session: Session):
    response = await agent.generate_str("Fetch example.com")
    await session.assert_that(
        Expect.tools.was_called("fetch"),
        response=response
    )
```

```python theme={null}
# Pytest style
@pytest.mark.asyncio
async def test_fetch_with_error(mcp_agent, mcp_session):
    response = await mcp_agent.generate_str("Fetch invalid-url")
    await mcp_session.assert_that(
        Expect.content.contains("error"),
        response=response
    )
```

### Debugger Example

The `mcp-eval-debugger` helps diagnose issues:

* Analyzes OTEL traces to find performance bottlenecks
* Identifies assertion failures and suggests fixes
* Troubleshoots configuration problems
* Explains error messages and stack traces

### Config Expert Example

The `mcp-eval-config-expert` helps with configuration:

```yaml theme={null}
# Optimized configuration for parallel execution
execution:
  max_concurrency: 10
  timeout_seconds: 60
  fail_fast: true

agents:
  definitions:
    - name: "fetch_agent"
      provider: anthropic
      model: claude-3-5-sonnet-20241022
      instruction: "You are a helpful assistant that can fetch URLs"
      server_names: ["fetch"]
```

## Best Practices

1. **Use the right subagent for the task** - Each subagent is specialized for specific aspects of mcp-eval
2. **Combine subagents** - Use multiple subagents together for complex tasks
3. **Provide context** - Give subagents information about your server's capabilities
4. **Review generated code** - Subagents provide excellent starting points, but review and customize as needed
5. **Keep subagents updated** - Pull the latest mcp-eval version for improved subagents

## Integration with mcp-agent

If you're using [mcp-agent](https://github.com/modelcontextprotocol/mcp-agent), these subagents are compatible with its agent loading system. Configure your `mcp-agent.config.yaml` to include the mcp-eval subagents search path.

## Contributing Subagents

To contribute new subagents:

1. Create a markdown file following the format in [`src/mcp_eval/data/subagents/`](https://github.com/lastmile-ai/mcp-eval/tree/main/src/mcp_eval/data/subagents)
2. Include the frontmatter with name, description, and tools
3. Write clear instructions for the subagent's expertise
4. Test the subagent with real mcp-eval tasks
5. Submit a pull request

## Related Resources

* [Generating Tests with LLMs](/test-generation) - Automated test generation
* [Agent Configuration](/agents) - Configure agents for testing
* [Best Practices](/best-practices) - General mcp-eval best practices
* [GitHub: Subagents Source](https://github.com/lastmile-ai/mcp-eval/tree/main/src/mcp_eval/data/subagents) - View all subagent definitions on GitHub