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

1. Add the MCP server

   Claude Code

   claude mcp add --transport http bryel https://mcp.bryel.ai/api/mcp
   
2. Authorize

   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.

3. Ask away

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

intents · report

Distribution per intent, top share, and an imbalanced flag (one intent dominating means the fine-tune overfits it).

redundancy · report

Unique vs duplicate inputs and the largest duplicate clusters (near-identical records waste capacity).

trajectoryHealth · report

Clean vs looping / errored trajectories, overall and per intent (errored or looping runs teach the model bad behavior).

length · report

Token and step distributions, with a count of records at risk of truncating at the fine-tune context limit.

modelMix · report

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 for the full curation and export flow.

To add records from outside bryel instead, bryel_add_records takes the chat-with-tools shape directly:

{
  "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.

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