Using Brim with an AI Coding Tool (via MCP)

Brim can connect to AI coding tools such as Claude Code and Codex through the Model Context Protocol (MCP). Once connected, you can work on a Brim project from the tool's chat: ask it to create or edit variables, check how well a variable is doing against your validation data, run generation on selected patients, and pull results, all without leaving your terminal.

This article explains what the connection does and how to set it up. The technical reference, including the full list of tools and setup for other clients, is at https://<your Brim server>/api/mcp/docs/.

What is MCP?

MCP is a standard way for an AI assistant to call tools in another product. Brim exposes a set of tools for one project at a time. Your coding tool sends requests to Brim on your behalf, using a project API token to prove who you are, and Brim does the work in that project.

Think of it as letting the assistant borrow your seat at your project. It can do what you could do in the Brim interface, so only connect tools and projects you want it to be able to change.

What you can do

Through the connection, your assistant can:

• See which project it is connected to, which models the project generates with, and how much of the token budget has been used.
• List the project's variables, dependent variables, patients, notes (titles and dates, not the text), and see the reference documents.
• Draft, create, and edit variables and dependent variables, including a whole hierarchy of a dependent variable and its inputs.
• Run generation for  patients and check on progress.
• Get a variable's scorecard and its agreement with your validation data, and use the disagreements to improve the definition.
• Fetch labels/results as a CSV.
• Upload notes, structured data, definitions, or validation files.

Some things are intentionally excluded. The connection reaches one project only. It never returns the text of a note, so notes do not pass through the assistant unless you upload them through it. And there are no tools for deleting projects, patients, notes, variables, or results. Those stay in the Brim interface.

Before you start

You need:

• Access to a Brim project.
• A project API token. See Creating a Brim API Token. Only project-level tokens work for MCP.
• A coding tool that supports MCP over HTTP with an authorization header. Claude Code and Codex CLI both do.

Connecting

1. Go to Settings > Manage Project in Brim.

2. On the row for an active token, click MCP. You can also create a token.

3. Copy the command or configuration for your tool and run it or paste it where the dialog says. The connection is named after you and the project, for example "brim-project1234", so you can tell projects apart if you connect more than one.

4. In your coding tool, check that the connection shows up. In Claude Code, run "/mcp". In Codex, run "codex mcp list".

Each token connects to one project. To work on another project, create a token in that project and add a second connection.

Working with the assistant

Start by asking which Brim project it is connected to, so you know changes go to the right place. Then describe what you want in plain language, for example "create a variable that captures the date of first chemotherapy" or "run the fever variable on the patients in the validation set and tell me where it disagrees with the gold values."

The assistant can make changes to variable definitions. Review them in Brim as you would any edit, and ideally use validation data so the assistant has something to measure against.

When Brim is updated

A coding tool remembers the list of Brim tools from when it connected. After a Brim release, reconnect  to pick up any new tools.

More detail

The reference guide at /api/mcp/docs/ on your Brim server covers setup for Cursor and VS Code, the full tool list, and a suggested first workflow.