Libraries & Refs

What the Library System Is

MCPLab libraries let you define shared servers, agents, and scenarios once, then reference them from many eval configs.

This reduces duplication and keeps team-wide defaults consistent.

Recommended Library Structure

• `servers.yaml` contains reusable MCP server definitions.
• `agents.yaml` contains reusable LLM agent definitions.
• `scenarios/` contains reusable scenario files.

mcplab/
├── servers.yaml
├── agents.yaml
└── scenarios/
    ├── scenario-a.yaml
    └── scenario-b.yaml

Suite Labels from Folder Paths

Eval configs placed in subfolders automatically derive a suite label from their folder path. The App groups and displays configs by suite in the Configurations page, making it easy to run or browse related configs together.

The suite label is the relative folder path from the evals root. A file at `evals/search/basic.yaml` gets the suite label "search".

evals/
├── search/
│   ├── basic.yaml       → suite: "search"
│   └── advanced.yaml    → suite: "search"
└── auth/
    └── login.yaml       → suite: "auth"

Reference Library Items in eval.yaml

Use `ref` entries to pull shared items into an eval config by id.

servers:
  - ref: my-server
agents:
  - ref: claude-sonnet
scenarios:
  - ref: scenario-a

How Ref Resolution Works

• Server refs resolve from `servers.yaml`.
• Agent refs resolve from `agents.yaml`.
• Scenario refs resolve from files in `scenarios/`.
• Missing refs are reported and should be fixed before running.

Use Libraries in App and CLI

• App: start with `--libraries-dir` so shared library content is loaded.
• CLI run: refs resolve when library files are present in the configured layout.
• App UI: inspect and manage shared items in the Library section.

npx @inspectr/mcplab app --libraries-dir ./mcplab