> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braingrid.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Using BrainGrid MCP
> Learn how to use the 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
Connect to your BrainGrid project automatically
Create from brief ideas or capture detailed requirements
Work with the requirements agent to refine and break down requirements
Generate implementation tasks using AI via MCP
Fetch and implement tasks for a requirement
View specific task information and content
Mark tasks as in progress or completed
Review a pull request against a requirement
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
```bash Basic Usage theme={null}
> Build REQ-123
⏺ I'll build requirement REQ-123 for you, fetching the tasks and getting you ready to implement.
```
```bash With Understanding Intent theme={null}
> 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.
```
```bash With Review Intent theme={null}
> 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.
```bash theme={null}
> 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:
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.
```bash theme={null}
> 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.
```bash theme={null}
> 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:
```bash theme={null}
> 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:
1. **Refine it** using the requirements agent in the [BrainGrid web app](https://app.braingrid.ai)
2. **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](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](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
```
**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](/quickstart) for step-by-step instructions with screenshots showing how to [write your first requirement](/quickstart#write-your-first-requirement-document) and [break it down into tasks](/quickstart#break-down-your-requirement-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.
```bash theme={null}
> 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](#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.
```bash Quick Start theme={null}
> 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...
```
```bash Understand First theme={null}
> 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?
```
```bash Review Acceptance Criteria theme={null}
> 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.
```bash Basic Task Retrieval theme={null}
> get task 1 of REQ-123
⏺ I'll fetch task 1 from REQ-123 with all the details you need to start implementing.
```
```bash Get Task with Context theme={null}
> 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.
```
```bash Get Next Logical Task theme={null}
> 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.
```
```bash Get Task with Time Estimate theme={null}
> 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.
```bash Simple Status Update theme={null}
> update task 1 of REQ-123 to COMPLETED
⏺ I'll mark task 1 as completed for you.
```
```bash Update with Progress Note theme={null}
> 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.
```
```bash Smart Progress Update theme={null}
> 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.
```bash Standard Acceptance Review theme={null}
> 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.
```
```bash Review for Stakeholder theme={null}
> 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.
```
```bash Technical Review Focus theme={null}
> 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.
```
```bash Pre-merge Checklist theme={null}
> 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
```bash theme={null}
# 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
```bash theme={null}
# "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
```bash theme={null}
# "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
**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.