Skip to main content
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

Save plans from Cursor or Claude Code as requirements

Refine Requirement

Work with the requirements agent to refine and break down requirements

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 - Captures your plans as trackable requirements (auto-detects your GitHub repo when possible)
  • 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.

​
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:
  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

You can create a plan in Cursor or Claude Code and then ask your AI assistant to save that plan as a requirement. This creates a requirement that you can then refine with BrainGrid’s requirements agent, break down into specific tasks, and build systematically. 
> Create a new requirement from the plan you made

⏺ I'll create a new requirement in BrainGrid based on the plan I
  made for implementing ....

⏺ braingrid - create_project_requirement (MCP) (message...)
Claude Code tip #1: Use plan mode to create a plan. Claude Code tip #2: Once you have then plan you want to save, hit “ESC” and say Create a new requirement from the plan you made You can optionally specify repositories to associate with the requirement. Provide a comma-separated list in the format owner/repo. 
> Create a new requirement and link owner/repo-one, owner/repo-two

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

⏺ braingrid - create_project_requirement (MCP) (message: "...", repositories: "owner/repo-one, owner/repo-two")
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
  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. 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
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.

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

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

  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.