> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bryel.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Coding agents
> Connect Claude Code, Cursor, or any MCP client to bryel to query traces, inspect dataset quality, and build fine-tune datasets from your editor.
bryel runs a remote MCP server so your coding agent can work with your own data: query trace runs with BQL, inspect a fine-tune dataset's quality, and build datasets without leaving the editor. It's OAuth-gated, scoped to one project, and read-only by default.
## Connect
```bash Claude Code theme={"theme":{"light":"github-light","dark":"github-dark"}}
claude mcp add --transport http bryel https://mcp.bryel.ai/api/mcp
```
```json Cursor (~/.cursor/mcp.json) theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"mcpServers": {
"bryel": { "url": "https://mcp.bryel.ai/api/mcp" }
}
}
```
```json VS Code (.vscode/mcp.json) theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"servers": {
"bryel": { "type": "http", "url": "https://mcp.bryel.ai/api/mcp" }
}
}
```
The first time your agent uses the server, a browser opens. Sign in to bryel and pick the project the agent may use. That project is bound to the connection; it's the only one this agent can ever see.
Leave **Allow write** off for read-only access (query and inspect). Turn it on only if you want the agent to create datasets and add records.
Try *"Using bryel, how many traces errored in the last 7 days, and which intents cost the most?"* or *"Inspect my `good-berlin-runs` dataset — is it balanced enough to fine-tune on?"*
## Tools
Ten tools, scoped to the single project you picked at consent. The agent can never name another project.
### Traces
| Tool | What it does |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `bryel_get_schema` | Lists the queryable fields, types, and operators, plus your project's **live** intent labels and model names. Call this first. |
| `bryel_validate_query` | Checks a BQL filter for errors (with did-you-mean suggestions) **without running it**. |
| `bryel_query_traces` | Runs a BQL filter and returns the match count plus a sample (model, status, tokens, cost, steps, tools, truncated input). |
### Datasets
| Tool | What it does |
| --------------------------------------- | ---------------------------------------------------------------------------------------- |
| `bryel_list_datasets` | Lists this project's fine-tune (SFT) datasets with record counts. |
| `bryel_inspect_dataset` | A full training-data quality report for one dataset (see below). |
| `bryel_export_dataset` | Exports a dataset as fine-tune JSONL to bryel storage; returns a job to poll. |
| `bryel_export_status` | Polls an export job; returns a download URL for the JSONL once it succeeds. |
| `bryel_create_dataset` write | Creates a new empty dataset; returns its slug. |
| `bryel_add_from_query` write | Curates real traces into a dataset — every trace matching a BQL filter becomes a record. |
| `bryel_add_records` write | Appends records in the bryel fine-tune shape (`{messages, tools?}`). |
The two **write** tools require **Allow write** at consent; otherwise they return a clear "read-only" error telling you to reconnect.
## BQL in 30 seconds
BQL is a filter expression over your traces. Strings use single quotes; combine clauses with `and`, `or`, and `not`.
```
status = 'error'
intent = 'add_pricing' and cost_usd > 0.5
tool_count >= 10 and repeated_calls > 0
model = 'anthropic/claude-opus-4-7'
```
Call `bryel_get_schema` to see every field, operator, and your project's actual intent labels and model names. See [Concepts](/concepts) for what a trace and intent are.
## Inspecting dataset quality
`bryel_inspect_dataset` returns the same metrics bryel uses to judge whether a dataset will train a good model, so your agent can curate before you export.
Distribution per intent, top share, and an `imbalanced` flag (one intent dominating means the fine-tune overfits it).
Unique vs duplicate inputs and the largest duplicate clusters (near-identical records waste capacity).
Clean vs `looping` / `errored` trajectories, overall and per intent (errored or looping runs teach the model bad behavior).
Token and step distributions, with a count of records at risk of truncating at the fine-tune context limit.
Which source models the records came from.
```
"Using bryel, list my datasets, inspect the largest one, and tell me what to
fix before fine-tuning."
```
## Building a dataset
With write enabled, an agent builds a fine-tune set without leaving the editor. The usual path curates your **real runs** — find good traces, then add the ones matching a filter:
```
"Using bryel: create a dataset 'good-add-pricing', then add every clean
add_pricing run from the last 30 days to it, and inspect the result."
```
That maps to `bryel_create_dataset` → `bryel_add_from_query` (e.g. `intent = 'add_pricing' and status = 'ok'`) → `bryel_inspect_dataset`. Adding from a query is idempotent per trace, so you can widen the filter and re-run without duplicating. See [Datasets](/guides/datasets) for the full curation and export flow.
To add records from outside bryel instead, `bryel_add_records` takes the chat-with-tools shape directly:
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"messages": [
{ "role": "user", "content": "Add a pricing section to the landing page." },
{ "role": "assistant", "content": null, "tool_calls": [ /* ... */ ] },
{ "role": "tool", "tool_call_id": "…", "content": "…" }
],
"tools": [ /* the tool schemas referenced above (optional) */ ]
}
```
`input` (the readable prompt) is derived from the first user message when you omit it. Add up to 500 records per `bryel_add_records` call.
```
"Create a bryel dataset 'good-berlin-runs', then add these trajectories to it."
```
## Give your agent the playbook
Paste this into your `AGENTS.md` / `CLAUDE.md` (or `.cursorrules`) so the agent uses bryel well.
```markdown theme={"theme":{"light":"github-light","dark":"github-dark"}}
## Using bryel (observability + fine-tune datasets)
You have bryel MCP tools, scoped to ONE project. Read-only unless write was
granted at consent.
Traces (BQL — a filter expression; single-quoted strings; and / or / not):
- `bryel_get_schema` — call FIRST to learn fields, operators, and the project's
real intent labels + model names.
- `bryel_validate_query` — check a BQL filter before running it.
- `bryel_query_traces` — run a BQL filter; returns a match count + sample rows.
e.g. status = 'error'
intent = 'add_pricing' and cost_usd > 0.5
tool_count >= 10 and repeated_calls > 0
Datasets (SFT fine-tune sets):
- `bryel_list_datasets` — list datasets + record counts.
- `bryel_inspect_dataset` — quality report: intent balance/imbalance,
redundancy + duplicate clusters, trajectory health (looping/errored), token &
step length (+ truncation risk), model mix.
- `bryel_create_dataset` (write) — make a new empty dataset; returns its slug.
- `bryel_add_from_query` (write) — add every trace matching a BQL filter to a
dataset as a record (idempotent per trace). The main way to build a set from
real runs: create_dataset -> add_from_query -> inspect_dataset.
- `bryel_add_records` (write) — append external records as {messages, tools?};
`input` is derived from the first user turn if omitted; ≤500 per call.
- `bryel_export_dataset` — export a dataset as fine-tune JSONL to storage;
returns a jobId.
- `bryel_export_status` — poll the jobId; returns a download URL once succeeded.
Build → inspect → export → train: create_dataset/add_from_query ->
inspect_dataset -> export_dataset -> export_status.
Use traces to investigate error rates, cost/token outliers, expensive intents,
repeated/looping tool calls, and slow runs. Use the dataset tools to judge a
fine-tune set's quality (balance, dedup, health, length) and to build one from
your real runs. Always ground on `bryel_get_schema` before writing a query.
```
One connection equals one project, chosen at consent, and read-only unless you turned on **Allow write**. To use a different project — or to change the read/write choice — reconnect and re-consent. Removing the connection (or losing access to the project) cuts off the agent immediately.