Scenario 1: your first test

Your "hello world" mcptest run. You have an MCP server binary on disk. You want one passing test that proves the binary speaks the protocol, lists at least one tool, and runs end-to-end through the mcptest matcher pipeline. This scenario is the minimum amount of YAML that makes that happen.

The example below assumes a placeholder stdio server you can swap for your own binary on the first line. Everything else is copy-pasteable.

The YAML

Save this as tests/first-test.yml:

# yaml-language-server: $schema=https://mcptest.sh/schema/v1.json

servers:
  local:
    command: ["./target/debug/my-mcp-server"]

tools:
  - name: "lists at least one tool without error"
    server: local
    tool: "list_tools"
    expect:
      - target: "result.tools"
        matcher:
          schema:
            type: array
            minItems: 1
        message: "server should advertise at least one tool"

compliance:
  - name: "initialize handshake succeeds"
    server: local
    check: "initialize"
    expect:
      - target: "result.protocolVersion"
        matcher:
          regex: "^2\\d{3}-\\d{2}-\\d{2}$"

Two tests in one file. The first calls a list_tools tool and asserts the response carries at least one element. The second runs the compliance initialize check and asserts the negotiated protocol version matches the MCP date-versioned format. Together they prove the binary boots, speaks the protocol, and exposes something callable.

How to run it

# validate the schema first (fast feedback on YAML errors)
mcptest validate tests/first-test.yml

# run the suite
mcptest run tests/first-test.yml

Expected output

mcptest run tests/first-test.yml

  PASS  initialize handshake succeeds              (12ms)
  PASS  lists at least one tool without error      (87ms)

2 passed, 0 failed in 99ms

If both tests pass, the binary is wired up. If initialize fails, your server is not yet speaking MCP. If list_tools passes initialize but fails the assertion, your server speaks MCP but does not advertise any tools yet.

Variations

• Replace the command. If your binary takes config, append flags: command: ["./target/debug/my-mcp-server", "--config", "fixtures/test.toml"].
• Use an npx package. The same shape works for any MCP server you can launch from a shell: command: ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp"].
• Add a second test. Once both green, add a real tool call against a known tool name.

See also

• docs/getting-started.md, the full install-to-first-run walk-through.
• docs/yaml-reference.md, every field this YAML uses, with the full type signatures.
• Next scenario: Performance budget.