Skip to main content
bt mcp runs tools exposed by the Braintrust MCP server from your terminal, without configuring an MCP client. It connects to the MCP server for your active profile or BRAINTRUST_API_KEY, discovers the server’s tools, and generates a subcommand for each tool with a flag for each of its arguments. Requires bt v0.28.0 or later.
The bt mcp command is in public preview and can change before reaching general availability.
Because the subcommands and flags come from the server, bt mcp connects before it prints help. Run bt login or set BRAINTRUST_API_KEY before you run bt mcp --help. bt mcp doesn’t appear in the bt --help command list.

​
bt mcp

Discover and run tools exposed by the Braintrust MCP server.

​
Usage

​
Commands

​
Options

bt mcp accepts the global options before or after the subcommand and tool name. Unless you pass --verbose, bt mcp suppresses non-essential output, as if you passed --quiet.

​
bt mcp list

List tools exposed by the Braintrust MCP server. bt mcp list prints one line per tool, with the tool name and the first sentence of its description separated by a tab. Descriptions longer than 120 characters are shortened and end with …. With --json, it prints a tools array containing each tool’s name, full description, and inputSchema.

​
Usage

​
Options

​
Examples

​
bt mcp run

Run a tool exposed by the Braintrust MCP server. bt mcp run <tool> calls one tool and prints its result. Run bt mcp list to see the tool names.

​
Usage

​
Arguments

​
Options

​
Examples

Each tool’s flags depend on the server. For example, bt mcp run search_docs --help prints the tool’s full description, followed by its usage, generated flags, and required fields. This excerpt omits the description and global options:

​
Input methods

bt mcp run accepts a tool’s arguments in three ways. Each is an alternative to the others, so you can’t combine them in one command.
  • Generated flags: One flag per argument in the tool’s input schema, such as --query for a query argument.
  • --args <JSON>: All arguments as one JSON object.
  • A file or stdin: A path to a file that contains a JSON object, or - to read the object from stdin.
Before calling the tool, bt checks the top-level arguments against the tool’s input schema. It reports missing required arguments and values of the wrong JSON type. When the schema sets additionalProperties to false, it also reports arguments the schema doesn’t define.

​
Required telemetry argument

Every tool on the Braintrust MCP server requires a telemetry argument. It’s an object whose intent string briefly describes your wider task and why you’re calling the tool. bt checks that telemetry is present, but it doesn’t check the fields inside it, so always include intent. Pass it with --telemetry '{"intent": "..."}' or include it in the JSON input. Don’t include argument values, personal information, or secrets in intent.

​
Generated flags

bt builds each tool’s flags from its input schema:
  • Flag names: Underscores in argument names become hyphens, so top_k becomes --top-k. An argument named args uses --tool-args, because --args passes JSON input.
  • Booleans: Take an explicit true or false value.
  • Numbers: Take a number, such as --top-k 3.
  • Objects and arrays: Take a JSON object or array, such as --telemetry '{"intent": "..."}'.
  • Strings: Take plain text. When an argument also accepts objects or arrays, a JSON object or array is passed as JSON and other text is passed as a string.
  • Nullable arguments: Take null to send a JSON null.

​
Output

When a tool returns structured content, bt mcp run prints it as formatted JSON. Otherwise, it prints the text content the tool returns. With --json, it prints the full tool result as JSON. If the tool reports an error, bt mcp run prints the error and exits with a nonzero status.