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

Available Tools

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

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)

Working with AI-Powered Tools

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

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

The project discovery workflow:

1. Checks if .braingrid/project.json exists locally (cached project info)
2. If not found, reads your git repository information
3. Queries BrainGrid API to find the matching project
4. 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:

Option 1: Create from brief ideas (AI refinement)

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.

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:

1. Access the requirements agent: Go to https://app.braingrid.ai/requirements and click "Create requirement" or open an existing requirement

2. 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

3. 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

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.

> 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?

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.

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.

Maximizing AI-Powered Development

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

1. AI as Collaborator: Your assistant understands context, makes intelligent decisions, and adapts to your specific situation

2. Tools as Instruments: MCP tools are flexible instruments your AI uses - not rigid commands you must learn

3. Intent Over Commands: Focus on what you want to accomplish, not how to invoke specific tools

4. Context Awareness: Your AI remembers your conversation context and adapts its tool usage accordingly