MCP Tools

The MCP server exposes the tools below. Your assistant picks the right ones on its own: a typical question starts with list_teams, loads the BNQL reference, drafts and validates a query, then runs it. Every tool call is scoped to the signed-in user, so results only ever come from teams you belong to. See the introduction for connecting and how access is authorised.

list_teams

List the teams the signed-in user belongs to, with your role and each team's plan. Call this first: every other Buildnote tool takes a team argument that must be one of the team ids returned here.

get_bnql_spec

Fetch the BNQL (Buildnote Query Language) reference: the full clause order, functions, operators, and the exact tables and fields you may query. BNQL is the ONLY way to read a team's collected data. Do not write BNQL from memory, because its rules and field names are non-obvious and easy to get wrong. Call this once before drafting a query and follow it exactly. Returns reference text only and queries nothing.

The same material is published here as the BNQL reference.

validate_query

Validate a BNQL query without running it: checks the syntax and that every table and field resolves against the schema. Returns VALID or INVALID with the reason. Validate a drafted query before running it with query_data.

Argument	Required	Description
query	yes	The BNQL query to validate

query_data

Run a BNQL query against the team's collected CI/CD events (tests, builds, pipelines, commits, files, metrics) and return the matching rows as JSONL, one JSON object per line. Include SINCE and UNTIL bounds to keep results relevant. Results are truncated after 2000 rows, so aggregate or LIMIT for less noise.

Argument	Required	Description
team	yes	Team id, one of the ids returned by list_teams
query	yes	A BNQL query, e.g. SELECT status, COUNT() AS total FROM tests GROUP BY status

Requires a plan with API access. See the BNQL reference for query syntax.

get_build_file

Fetch the content of a file collected during a build (logs, reports, coverage, screenshots, etc.). Find files first with a query_data query on the files table selecting org, project, module, build, name and path, then pass those exact values and never guess them. Text files are returned as text (truncated after 50000 characters); images and other binary files are returned base64-encoded, up to 4 MiB.

Argument	Required	Description
team	yes	Team id, one of the ids returned by list_teams
org	yes	Organisation id from a builds or files query row
project	yes	Project id from a builds or files query row
module	yes	Module id from a builds or files query row
build	yes	Build id from a builds or files query row
path	yes	File name or path from a files query row

Example Prompts

Once connected, ask questions in plain language and the assistant works out the queries:

Which of our test suites had the highest failure rate this week?

Show me the ten slowest builds in the payments project this month.

Find the build log from the latest failed build and summarise what went wrong.

The assistant answers with data from your events, and you can ask it to refine, compare periods, or dig into a specific build from there.