# Braintrust — how to use (mcp.ai)

Connect your Braintrust account and use 17 tools for artificial intelligence straight from your AI agent. Connect with your own API key. Braintrust is an AI engineering platform for managing prompts, datasets, experiments, evaluations, observability, and production AI applications.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_braintrust?ms=1787293380000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `braintrust_create_dataset`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/braintrust`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/braintrust/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/braintrust/create/dataset` — Create a named dataset under a Braintrust project, or return the existing dataset unchanged when its name already exists in that project.
  - body: { name: string, tags?: string[], metadata?: object, project_id: string, description?: string }
- `POST https://api.mcp.ai/api/braintrust/create/experiment` — Create an experiment under a Braintrust project. When its name already exists, Braintrust returns the existing experiment unchanged unless ensure_new is true, which creates an experiment with a unique
  - body: { name?: string, tags?: string[], public?: boolean, metadata?: object, dataset_id?: string, ensure_new?: boolean, project_id: string, description?: string, dataset_version?: string, base_experiment_id?: string }
- `POST https://api.mcp.ai/api/braintrust/create/project` — Create a Braintrust project, or return the existing project unchanged when its name already exists.
  - body: { name: string, org_name?: string, description?: string }
- `POST https://api.mcp.ai/api/braintrust/create/prompt` — Upsert a versioned prompt configuration under a Braintrust project without invoking it. The same project and slug reuse the prompt ID but create a new version that replaces the stored prompt configura
  - body: { name: string, slug: string, tags?: string[], project_id: string, description?: string, prompt_data?: object, function_type?: string, template_format?: string }
- `POST https://api.mcp.ai/api/braintrust/delete/project` — Soft-delete a Braintrust project and return its deletion state.
  - body: { project_id: string }
- `POST https://api.mcp.ai/api/braintrust/delete/resource` — Delete one Braintrust experiment, dataset, or prompt by UUID for explicit lifecycle cleanup.
  - body: { resource_id: string, resource_type: string }
- `POST https://api.mcp.ai/api/braintrust/fetch/events` — Fetch one newest-to-oldest page of project log, experiment, or dataset events.
  - body: { limit?: integer, version?: string, next_cursor?: string, resource_id: string, resource_type: string }
- `POST https://api.mcp.ai/api/braintrust/get/resource` — Get one project, experiment, dataset, prompt, or function by UUID.
  - body: { resource_id: string, resource_type: string }
- `POST https://api.mcp.ai/api/braintrust/insert/dataset/events` — Upsert a batch of examples into an existing Braintrust dataset. New or omitted IDs insert events; an existing supplied ID replaces that event's current values.
  - body: { events: object[], dataset_id: string }
- `POST https://api.mcp.ai/api/braintrust/insert/experiment/events` — Upsert a batch of result events into an existing Braintrust experiment. New or omitted IDs insert events; an existing supplied ID replaces that event's current values.
  - body: { events: object[], experiment_id: string }
- `POST https://api.mcp.ai/api/braintrust/list/resources` — List and filter one page of projects, experiments, datasets, prompts, or functions visible to the connected Braintrust API key.
  - body: { ids?: string[], name?: string, slug?: string, limit?: integer, version?: string, org_name?: string, project_id?: string, environment?: string, next_cursor?: string, project_name?: string, resource_type: string }
- `POST https://api.mcp.ai/api/braintrust/query/data` — Run one bounded synchronous read-only BTQL query over Braintrust project logs, an experiment, or a dataset. The first-page query must end with a positive LIMIT; continue later pages by passing the ret
  - body: { query?: string, version?: string, lint_mode?: string, tz_offset?: number, next_cursor?: string }
- `POST https://api.mcp.ai/api/braintrust/summarize/resource` — Return metadata and optional aggregate summaries for one Braintrust experiment or dataset.
  - body: { resource_id: string, resource_type: string, include_aggregates?: boolean, comparison_experiment_id?: string }
- `POST https://api.mcp.ai/api/braintrust/update/dataset` — Update the name, description, tags, or metadata of a Braintrust dataset. At least one non-null mutable field is required.
  - body: { name?: string, tags?: string[], metadata?: object, dataset_id: string, description?: string }
- `POST https://api.mcp.ai/api/braintrust/update/experiment` — Update selected metadata and linkage fields on a Braintrust experiment. At least one non-null mutable field is required.
  - body: { name?: string, tags?: string[], public?: boolean, metadata?: object, dataset_id?: string, description?: string, experiment_id: string, dataset_version?: string, base_experiment_id?: string }
- `POST https://api.mcp.ai/api/braintrust/update/project` — Update selected fields of a Braintrust project. At least one non-null mutable field is required: name, description, or settings.
  - body: { name?: string, settings?: object, project_id: string, description?: string }
- `POST https://api.mcp.ai/api/braintrust/update/prompt` — Update a Braintrust prompt's metadata or configuration without invoking it. At least one non-null mutable field is required.
  - body: { name?: string, slug?: string, tags?: string[], prompt_id: string, description?: string, prompt_data?: object, template_format?: string }

## Example prompts
- "What can I do in Braintrust?"
- "Show me a summary of my Braintrust account"

## More
- Page: https://mcp.ai/braintrust
- Agent spec (llms.txt): https://mcp.ai/braintrust/llms.txt
- Postman collection: https://mcp.ai/braintrust/postman.json