Using BrainGrid MCP

Once you’ve installed BrainGrid MCP, you can use natural language to manage requirements and tasks directly from your AI assistant.

Common Workflows

Discover Project

Connect to your BrainGrid project automatically

Create New Requirement

Create from brief ideas or capture detailed requirements

Refine Requirement

Work with the requirements agent to refine and break down requirements

Break Down Requirement

Generate implementation tasks using AI via MCP

Build Requirement

Fetch and implement tasks for a requirement

Get Task Details

View specific task information and content

Update Task Status

Mark tasks as in progress or completed

Acceptance Review

Review a pull request against a requirement

Server Information

Check server status and authentication

Available Tools

BrainGrid MCP provides these tools that your AI assistant uses intelligently based on your intent:

Important: These are not rigid commands you call directly. Your AI assistant uses these tools flexibly to accomplish what you’re trying to achieve.

Project Discovery

Tools to discover and connect to your BrainGrid projects:

get_project - Discovers your BrainGrid project from your git repository and caches project context locally
get_profile - Retrieves your user profile and organization information

Requirement Management

Your AI assistant can use these tools to help you work with requirements in whatever way makes sense for your situation:

create_project_requirement - Creates requirements from brief ideas using AI refinement (for when you have a rough concept)
capture_project_requirement - Captures pre-written requirements with full details (for when you already have detailed content)
breakdown_project_requirement - Breaks down existing requirements into implementation tasks using AI
list_project_requirements - Lists all requirements in your project with filtering options
get_project_requirement - Retrieves detailed requirement information including content and acceptance criteria
update_project_requirement - Updates requirement properties like status, name, or assignee
build_project_requirement - Fetches requirements and tasks, adapting the presentation to your needs
acceptance_review - Reviews pull requests against requirements from multiple perspectives

Task Management

Flexible task operations that adapt to your workflow:

list_project_tasks - Lists all tasks for a requirement with filtering and pagination
create_project_task - Creates new tasks within a requirement
get_project_task - Retrieves detailed task information with implementation content
update_project_task - Updates task status, content, and properties

Information & Status

Context and authentication tools your assistant uses as needed:

info - Provides server status, version information, and available tools
auth_status - Checks authentication status and displays user information
authenticate - Initiates browser-based authentication (stdio mode only)
logout - Clears stored credentials and logs out (stdio mode only)

Key Insight: Instead of memorizing tool parameters, focus on expressing your goals. Your AI assistant will use these tools in the right combination to accomplish what you want.

Working with AI-Powered Tools

Key Concept: MCP tools are not rigid commands like traditional CLI tools. They are flexible instruments that your AI assistant uses intelligently based on your natural language intent.

Unlike traditional software where build_project_requirement always does the same thing, BrainGrid’s MCP tools adapt to your specific needs:

Express Your Intent, Not Just Commands

Instead of thinking: “I need to call the build_project_requirement tool” Think: “I want to understand this requirement and start working on it”

Examples of Intent-Driven Usage

> Build REQ-123

⏺ I'll build requirement REQ-123 for you, fetching the tasks and getting you ready to implement.

> Build REQ-123, I want to understand all the tasks before we start building

⏺ I'll get REQ-123 and walk you through each task so you understand the full scope before we begin implementation.

> Build REQ-123 but first show me the acceptance criteria for each task

⏺ I'll get the requirement and break down the acceptance criteria for each task so you can see what success looks like.

The Power of Natural Language

Your AI assistant can:

Adapt tool usage based on your specific goals
Combine multiple tools in intelligent sequences
Ask clarifying questions when your intent needs refinement
Provide context and explanations tailored to your needs

Pro Tip: Don’t just say what tool to use—tell your AI assistant what you’re trying to accomplish. Let it figure out the best way to use the tools to meet your needs.

Workflows

Discover your project

Before creating requirements or working with tasks, your AI assistant needs to know which BrainGrid project you’re working with. The get_project tool discovers your project automatically.

> What project am I working on?

⏺ Let me check which BrainGrid project is linked to this repository...

⏺ braingrid - get_project (MCP)

⏺ ✅ Project discovered successfully!
  - Name: My Awesome App
  - ID: PROJ-123
  - Repository: owner/my-awesome-app

Automatic Discovery: Your AI assistant automatically runs get_project when needed. It discovers your project by looking at your git repository and caches the project information locally in .braingrid/project.json for faster access.

The project discovery workflow:

Checks if .braingrid/project.json exists locally (cached project info)
If not found, reads your git repository information
Queries BrainGrid API to find the matching project
Caches project details locally for future use

Once discovered, all subsequent operations (creating requirements, listing tasks, etc.) automatically use this project context.

Create a new requirement

There are two ways to create requirements in BrainGrid, depending on how much detail you already have: Use create_project_requirement when you have a rough concept or brief description. The AI will refine it into a structured requirement with detailed content, acceptance criteria, and complexity ratings.

> Create a requirement for user authentication with OAuth

⏺ I'll create a new requirement using AI to refine your idea into
  a detailed requirement with acceptance criteria.

⏺ braingrid - create_project_requirement (MCP)

Best for: Quick ideas, rough concepts, feature requests that need structure

Option 2: Capture pre-written requirements

Use capture_project_requirement when you already have a detailed requirement with full content and acceptance criteria written out.

> Capture this requirement: [detailed requirement text with acceptance criteria]

⏺ I'll capture your pre-written requirement in BrainGrid.

⏺ braingrid - capture_project_requirement (MCP)

Best for: Requirements you’ve already detailed in a plan, pre-written specifications, documented feature requests You can optionally specify repositories to associate with either type of requirement:

> Create a requirement for user auth and link owner/repo-one, owner/repo-two

⏺ I'll create a new requirement and associate the specified repositories.

⏺ braingrid - create_project_requirement (MCP) (repositories: "owner/repo-one, owner/repo-two")

Claude Code tip: Use plan mode to create a plan, then hit “ESC” and say Create a new requirement from the plan you made Note: If repositories is not provided, the server will attempt to auto-detect the current GitHub repository from your local git configuration.

Project Context Required: The create_project_requirement tool needs to know which project to create the requirement in. If you haven’t run get_project yet, your AI assistant will automatically discover your project first.

What’s next? After creating a requirement via MCP, you’ll typically want to:

Refine it using the requirements agent in the BrainGrid web app
Build it using MCP in your AI coding tool

This two-stage approach lets you do detailed requirement work in the web interface, then seamlessly build via MCP.

Refine and break down a requirement

Once you’ve created a requirement, you’ll often need to refine it and break it down into actionable tasks. This is where BrainGrid’s requirements agent becomes invaluable. What is the requirements agent? The requirements agent is an AI assistant built into the BrainGrid web app at https://app.braingrid.ai. It helps you write detailed requirement documents and break them down into implementation tasks. The requirements agent can help you:

Write and refine detailed requirement documents
Ask clarifying questions to better understand your needs
Break down complex features into specific implementation tasks
Add acceptance criteria and technical specifications
Ensure requirements are ready for your AI coding tools

How it works:

Access the requirements agent: Go to https://app.braingrid.ai/requirements and click “Create requirement” or open an existing requirement
Work with the agent: The requirements agent will help you write and refine your requirement document by:
- Asking clarifying questions about your needs
- Writing detailed requirement specifications
- Adding technical details and acceptance criteria
- Breaking the requirement down into specific implementation tasks
Use MCP to build: Once your requirement is refined and has tasks, use the MCP to fetch it and start building

Example workflow:

Web App: Create/refine "user authentication" requirement 
↓ Requirements agent asks: What auth methods? 2FA needed? User management scope?
↓ Agent writes detailed requirement with acceptance criteria
↓ Agent breaks it down into 5 specific implementation tasks
↓ Switch to Cursor, Claude Code, or your MCP-enabled IDE
↓ 
MCP: "Build REQ-123" → Your AI coding tool fetches the refined requirement and tasks

Pro tip: Work with the requirements agent until your requirement has clear, actionable tasks. Well-defined requirements lead to smoother implementation and better results.

Need detailed guidance? See our Quickstart guide for step-by-step instructions with screenshots showing how to write your first requirement and break it down into tasks.

Alternative: Break down requirements via MCP

If you prefer to stay in your AI coding environment, you can use the breakdown_project_requirement tool to generate tasks using AI without switching to the web app.

> Break down REQ-123 into implementation tasks

⏺ I'll use AI to analyze REQ-123 and generate actionable implementation tasks.

⏺ braingrid - breakdown_project_requirement (MCP)

⏺ ✅ Generated 5 tasks for REQ-123:
  1. Set up database schema for user authentication
  2. Implement OAuth2 provider integration
  3. Create authentication middleware
  4. Build user session management
  5. Add frontend login/logout flows

When to use MCP breakdown:

You want to stay in your coding environment
The requirement content is already well-defined
You need quick task generation without detailed refinement

When to use the web app requirements agent:

You need interactive refinement and clarification
The requirement needs significant detail work
You want to collaborate with your team on requirement structure

Both approaches produce the same result - a requirement with actionable tasks ready to build.

Build a requirement

Once you have a requirement with tasks broken down (see Refine and break down a requirement above), you can work with it in many different ways by expressing your intent in natural language.

Remember: You’re not limited to just “Build REQ-123”. Express what you want to accomplish and let your AI assistant use the tools intelligently to meet your needs.

> Build REQ-123

⏺ I'll get REQ-123 ready for you to start implementing. 
Let me fetch the requirement and its tasks.

⏺ The requirement has 5 tasks. Here's task 1 to get you started...

> Build REQ-123, I want to understand all the tasks before we start building

⏺ I'll fetch REQ-123 and walk you through each task so you understand 
the full scope before implementation.

⏺ **Task Overview for REQ-123:**
   - Task 1: Database schema updates (estimated 2 hours)
   - Task 2: API endpoint implementation (estimated 4 hours)
   - Task 3: Frontend integration (estimated 3 hours)
   
   Would you like me to explain any of these in detail before we begin?

> Build REQ-123 but first show me the acceptance criteria for each task

⏺ I'll get the requirement and break down what success looks like for each task.

⏺ **Acceptance Criteria Summary:**
   
   **Task 1**: Database schema must support user roles, pass all migrations
   **Task 2**: API must handle authentication, return proper error codes
   **Task 3**: Frontend must be responsive, include proper validation
   
   Ready to dive into the details of any specific task?

Pro Tip: Combine multiple intents in one request: “Build REQ-123, commit after the task has been marked complete and all tests pass.”

Get a task

Getting a task is flexible - you can express different intents about how you want to work with tasks. Your AI assistant uses get_project_task to retrieve task details.

> get task 1 of REQ-123

⏺ I'll fetch task 1 from REQ-123 with all the details you need to start implementing.

> get task 1 of REQ-123, I want to understand how it relates to the other tasks

⏺ I'll get task 1 and explain how it fits into the overall requirement and its dependencies with other tasks.

> get the next task I should work on with REQ-123

⏺ Let me look at REQ-123's tasks and your progress to suggest which task makes the most sense to tackle next.

> get task 2 of REQ-123 and help me estimate how long it will take

⏺ I'll fetch task 2 and break down the work involved to give you a realistic time estimate based on the complexity.

Update a task

Task status updates can be simple or include additional context and planning. Your AI assistant uses update_project_task to update task properties.

> update task 1 of REQ-123 to COMPLETED

⏺ I'll mark task 1 as completed for you.

> update task 2 of REQ-123 to IN_PROGRESS, I'm working on the API endpoints

⏺ I'll mark task 2 as in progress and can help you with API endpoint implementation as you work through it.

> I just finished the user authentication part of REQ-123, help me update progress and plan next steps

⏺ Let me look at your requirement to understand which task this completes and suggest what to work on next based on your progress.

Smart Updates: Your AI assistant can help determine which tasks to update based on what you’ve accomplished, suggest next steps, and even identify blockers before they slow you down.

Acceptance review on a pull request

PR reviews can be tailored to different perspectives and focus areas.

> acceptance review https://github.com/owner/repo/pull/123 against REQ-123

⏺ I'll validate the pull request against REQ-123's acceptance criteria and requirements.

> acceptance review https://github.com/owner/repo/pull/123 against REQ-123, I need to present findings to the product team

⏺ I'll review the PR with a focus on user-facing changes and business requirements that the product team cares about.

> acceptance review https://github.com/owner/repo/pull/123 against REQ-123, focus on architecture and performance

⏺ I'll examine the PR's technical implementation, architecture decisions, and performance implications against the requirement.

> before I merge this PR, verify it meets all requirements in REQ-123

⏺ I'll run a comprehensive pre-merge check ensuring the PR fully satisfies REQ-123 and is ready for production.

Multi-perspective Reviews: Your AI assistant can review PRs from different angles - technical, business, user experience, or compliance - based on your specific needs and audience.

Maximizing AI-Powered Development

Mindset Shift: You’re not operating a traditional tool - you’re collaborating with an intelligent assistant that uses MCP tools to understand and accomplish your development goals.

Best Practices for Intent-Driven Development

Express Context and Goals

# Instead of: "get task 1"
# Try: "get the next task I should work on, I'm strongest with backend APIs"

# Instead of: "build REQ-123"  
# Try: "build REQ-123, help me understand the architecture decisions needed"

Combine Multiple Intents

# "Build REQ-456, break down the complexity of each task, and suggest an order 
#  based on my team's frontend-heavy skillset"

# "Review REQ-789 focusing on security, and help me prepare talking points 
#  for the architecture review meeting"

Ask for Guidance

# "I'm new to this codebase - help me understand REQ-234 and suggest how 
#  to approach it safely"

# "REQ-345 seems complex - can you break it down and identify any risks 
#  I should discuss with my team first?"

Key Mental Models

AI as Collaborator: Your assistant understands context, makes intelligent decisions, and adapts to your specific situation
Tools as Instruments: MCP tools are flexible instruments your AI uses - not rigid commands you must learn
Intent Over Commands: Focus on what you want to accomplish, not how to invoke specific tools
Context Awareness: Your AI remembers your conversation context and adapts its tool usage accordingly

Remember: The more context you provide about your goals, constraints, and preferences, the better your AI assistant can help you achieve successful outcomes with BrainGrid.

​Common Workflows

Discover Project

Create New Requirement

Refine Requirement

Break Down Requirement

Build Requirement

Get Task Details

Update Task Status

Acceptance Review

Server Information

​Available Tools

​Project Discovery

​Requirement Management

​Task Management

​Information & Status

​Working with AI-Powered Tools

​Express Your Intent, Not Just Commands

​Examples of Intent-Driven Usage

​The Power of Natural Language

​Workflows

​Discover your project

​Create a new requirement

​Option 1: Create from brief ideas (AI refinement)

​Option 2: Capture pre-written requirements

​Refine and break down a requirement

​Alternative: Break down requirements via MCP

​Build a requirement

​Get a task

​Update a task

​Acceptance review on a pull request

​Maximizing AI-Powered Development

​Best Practices for Intent-Driven Development

​Express Context and Goals

​Combine Multiple Intents

​Ask for Guidance

​Key Mental Models

Common Workflows

Available Tools

Project Discovery

Requirement Management

Task Management

Information & Status

Working with AI-Powered Tools

Express Your Intent, Not Just Commands

Examples of Intent-Driven Usage

The Power of Natural Language

Workflows

Discover your project

Create a new requirement

Option 1: Create from brief ideas (AI refinement)

Option 2: Capture pre-written requirements

Refine and break down a requirement

Alternative: Break down requirements via MCP

Build a requirement

Get a task

Update a task

Acceptance review on a pull request

Maximizing AI-Powered Development

Best Practices for Intent-Driven Development

Express Context and Goals

Combine Multiple Intents

Ask for Guidance

Key Mental Models