> ## Documentation Index > Fetch the complete documentation index at: https://docs.braintrust.dev/llms.txt > Use this file to discover all available pages before exploring further. # bt mcp > Run Braintrust MCP server tools from the terminal without configuring an MCP client. bt mcp generates a subcommand and flags for each tool. `bt mcp` runs tools exposed by the [Braintrust MCP server](https://docs.braintrust.dev/integrations/developer-tools/mcp.md) 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. > [!WARNING] > > The bt mcp command is in [public preview](https://docs.braintrust.dev/feature-lifecycle.md) 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`](https://docs.braintrust.dev/reference/cli/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 ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} bt mcp [OPTIONS] ``` ### Commands | Command | Description | | - | - | | [`list`](#bt-mcp-list) | List tools exposed by the Braintrust MCP server | | [`run`](#bt-mcp-run) | Run a tool exposed by the Braintrust MCP server | ### Options | Option | Description | | - | - | | `-h`, `--help` | Print help | `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`. > [accordion] Global options > > | Option | Description | > | - | - | > | `--json` | Output as JSON | > | `-v`, `--verbose` | Increase output verbosity Env: `BRAINTRUST_VERBOSE` | > | `-q`, `--quiet` | Reduce interactive UI output Env: `BRAINTRUST_QUIET` | > | `--no-color` | Disable ANSI color output Env: `BRAINTRUST_NO_COLOR` | > | `--no-input` | Disable all interactive prompts Env: `BRAINTRUST_NO_INPUT` | > | `--profile ` | Use a saved login profile Env: `BRAINTRUST_PROFILE` | > | `--prefer-profile` | Prefer profile credentials even if `BRAINTRUST_API_KEY` is set | > | `--api-url ` | Override API URL Env: `BRAINTRUST_API_URL` | > | `--app-url ` | Override app URL Env: `BRAINTRUST_APP_URL` | > | `--app-public-url ` | Override public app URL for generated links Env: `BRAINTRUST_APP_PUBLIC_URL` | > | `--ca-cert ` | Path to a PEM-encoded CA bundle used for HTTPS requests Env: `BRAINTRUST_CA_CERT` | > | `--env-file ` | Path to a `.env` file to load before running commands Env: `BRAINTRUST_ENV_FILE` | > | `-o`, `--org ` | Override active org Env: `BRAINTRUST_ORG_NAME` | > | `-p`, `--project ` | Override active project Env: `BRAINTRUST_DEFAULT_PROJECT` | ## 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 ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} bt mcp list [OPTIONS] ``` ### Options | Option | Description | | - | - | | `-h`, `--help` | Print help | ### Examples ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} bt mcp list bt mcp list --json ``` ## bt mcp run Run a tool exposed by the Braintrust MCP server. `bt mcp run ` calls one tool and prints its result. Run `bt mcp list` to see the tool names. ### Usage ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} bt mcp run [OPTIONS] [FILE|-] ``` ### Arguments | Argument | Description | | - | - | | `` | Name of the tool to run, such as `search_docs` | | `[FILE\|-]` | Read tool arguments from a JSON file, or from stdin with `-` | ### Options | Option | Description | | - | - | | `--args ` | Pass tool arguments as a JSON object | | `-- ` | Generated flag for each argument in the tool's input schema, such as `--query` and `--top-k` for `search_docs`. See [Generated flags](#generated-flags) | | `-h`, `--help` | Print help. With a tool name, `-h` prints a summary and `--help` prints the tool's full description, its generated flags, and its required fields | ### Examples ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} bt mcp run search_docs --query "Setting up scorers" --top-k 3 \ --telemetry '{"intent": "Find scorer setup docs"}' bt mcp run search_docs --args '{"query": "Using metadata fields", "telemetry": {"intent": "Find metadata docs"}}' bt mcp run search_docs arguments.json echo '{"query": "Prompt playground features", "telemetry": {"intent": "Find playground docs"}}' | bt mcp run search_docs - bt mcp run search_docs --help ``` 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: ```text wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} Usage: bt mcp run search_docs [OPTIONS] [FILE|-] Arguments: [FILE|-] Read tool arguments from a JSON file, or from stdin with - Options: --args Pass tool arguments as a JSON object --query A search string to find relevant documentation. The string will be embedded and then used to search for relevant snippets in a vector database. --telemetry --top-k The number of top relevant document snippets to return. Higher values return more results but may include less relevant snippets. -h, --help Print help (see a summary with '-h') Required fields: query, telemetry. Provide them with generated flags or --args. ``` ## 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 `**: 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.