BLACKBOX AI MCP

​

Overview

​

Getting Started

1. Access MCP Token Section
   Navigate to cloud.blackbox.ai, log in, and go to your profile settings. Locate the “MCP Token” section.
2. Generate or Regenerate Token
   Click the generate button to create a new MCP token or regenerate an existing one for security.
3. Copy the Command
   Copy the pre-generated command or use the token in the following format. This command connects your Blackbox CLI to the MCP server.
4. Connect MCP Server in Terminal
   Open your terminal and run the command you have copied from MCP Setup Command or the following command:
   Copy

   blackbox mcp add remote-code https://cloud.blackbox.ai/api/mcp -t http -H "Authorization: Bearer <Your_Token_here>"
   
   Replace <Your_Token_here> with your actual token.
5. Verify Connection
   Start a new Blackbox CLI instance by running blackbox. You should see “using 1:MCP server” in the terminal, indicating a successful connection.

​

How It Works

• Explore Available Tools
  Use the keyboard shortcut “Ctrl + t” or simply ask the CLI: "print all the remote-code tools" to list all available tools and their capabilities.
• View Existing Tasks
  Query your tasks by saying: "Get all my tasks" to retrieve a list of current and past tasks.
• Start a New Task
  Initiate tasks naturally, e.g., "Start a new task on test_chat repo on main branch to add a stripe integration to handle payments." Specify the repository and branch in natural language. The task will be created and executed remotely. You can verify the same via Blackbox Cloud UI in browser.
• Monitor Task Progress
  Tasks run autonomously on the remote agent. Check status and details via CLI queries or view them in the Blackbox Cloud UI.

​

Using /remote Commands

Command Syntax

/remote <task-description> [<repo-specification>] [--branch <branch-name>]

• <task-description>: Description of the task you want to execute
• <repo-specification> (optional): Repository identifier (see formats below). If omitted and you’re inside a Git repository, the current repository is automatically used
• --branch <branch-name> (optional): Specify an existing branch or create a new one. If omitted and you’re inside a Git repository, the current branch is automatically used as the base branch

Automatic Git Context Detection

1. Automatic Repository Detection: If you’re inside a Git repository and don’t specify a repository, /remote automatically uses the current repository
2. Automatic Branch Detection: If you don’t specify a --branch, the current branch you’re on becomes the base branch for the pull request
3. Explicit Override: You can always explicitly specify a different repository or branch to override the automatic detection

# Inside /path/to/my-project (a Git repo on branch 'develop')
/remote add authentication feature

• Use the current repository (my-project)
• Create a new blackboxai/ branch
• Raise a PR to develop (your current branch)

# Override the base branch while using current repo
/remote fix bug --branch main

• Use the current repository
• Create a new blackboxai/ branch
• Raise a PR to main (specified branch, not your current branch)

# Work on a completely different repository
/remote add tests username/other-repo --branch main

• Use username/other-repo (explicitly specified)
• Ignore the current repository context
• Create a new blackboxai/ branch
• Raise a PR to main branch of username/other-repo

# Not inside any Git repository
/remote create a simple calculator app

• Execute the task in a sandbox environment
• No GitHub repository will be used
• No pull request will be created
• The agent will work on the task and provide results directly

• Quick prototyping and testing
• Creating standalone scripts or utilities
• Experimenting with code without repository setup
• Learning and exploration tasks

• Faster Workflow: No need to type repository names when working on your current project
• Context-Aware: Automatically uses your current branch as the base branch
• Flexible: Can still specify different repositories or branches when needed
• Seamless Integration: Works naturally with your local development workflow
• Sandbox Fallback: Works even without a Git repository for quick tasks and prototyping

Repository Specification Formats

1. Username/Repository Format:
   Copy

   /remote fix bug username/my-repo
   
   This format works for:
   • Your own repositories
   • Open-source repositories
   • Public repositories
   • Any GitHub repository you have access to Examples:
   Copy

   /remote add authentication john/my-web-app
   /remote add tests facebook/react --branch main
   /remote fix bug microsoft/vscode --branch bugfix
   
2. Full Repository URL (using --repo-url):
   Copy

   /remote implement feature --repo-url https://github.com/username/repository
   
3. Natural Language (repository mentioned in task description):
   Copy

   /remote add stripe integration to username/my-web-app repository
   

Branch Behavior

• With --branch specified:
  • A new branch is automatically created with the prefix blackboxai/
  • The agent works on this new branch
  • A pull request is raised to the base branch you specified
  • Important: The base branch must be accessible/exist in the repository, otherwise the task will fail
• Without --branch specified:
  • A new branch is automatically created with the prefix blackboxai/
  • The agent works on this new branch
  • A pull request is raised to the default branch (usually main or master)

/remote add feature username/repo --branch develop

1. Create a new branch like blackboxai/add-feature-xyz
2. Make changes on that new branch
3. Raise a PR from blackboxai/add-feature-xyz → develop (base branch)

Usage Examples

# Inside your local Git repository
/remote add stripe payment integration
# Uses current repo and current branch as base

/remote fix authentication bug --branch main
# Uses current repo but targets 'main' branch as base

/remote refactor user service
# Uses current repo and current branch as base

# Work on a different repository while inside another
/remote add documentation microsoft/vscode

# Work on open-source repository
/remote implement dark mode facebook/react --branch feature/dark-mode

# Work on your own repository (when not inside it)
/remote fix authentication bug john/my-api --branch main

/remote implement user dashboard --repo-url https://github.com/username/my-project --branch feature/dashboard

/remote add payment processing to the <user-name>/e-commerce-backend repository on main branch

Alternative Syntax

/remote add dark mode support username/my-app main

/remote implement API endpoints --repo-url https://github.com/username/api-service main

Workflow

1. Execute Command: Type the /remote command with your task description and repository
2. Branch Creation: If needed, a new branch is automatically created
3. Task Execution: The remote agent processes your task autonomously on Blackbox Cloud
4. Monitor Progress: Track execution in real-time via:
   • CLI queries and status updates
   • cloud.blackbox.ai - View detailed task execution logs
5. Review Changes: Check the pull request created by the agent on:
   • Your GitHub repository
   • cloud.blackbox.ai - View all PRs and task results

Monitoring Tasks on Blackbox Cloud

Via Blackbox Cloud Web Interface

• Task Dashboard: View all your running and completed tasks
• Execution Logs: See detailed logs of what the agent is doing in real-time
• Pull Requests: Review all PRs created by the agent
• Task Status: Check progress, errors, and completion status
• Task History: Access previous tasks and their outcomes

Via Blackbox CLI

What's the status of task [task-id]?

• Current execution status
• Progress updates
• Any errors or issues
• Completion status
• Link to the pull request (if completed)

# After running a /remote command, you'll receive a task ID
/remote add authentication john/my-app --branch main
# Task created: task-abc123

# Later, check the status
What's the status of task task-abc123?

Tips

• Work Locally: When inside a Git repository, simply run /remote <task> without specifying the repository - it will automatically use your current repo and branch
• Sandbox Mode: When NOT inside a Git repository and no repo is specified, the task executes in a sandbox environment without GitHub integration - perfect for quick prototyping
• Override When Needed: Explicitly specify a repository or branch to override automatic detection
• Current Branch as Base: When working locally without specifying --branch, your current branch becomes the base branch for the PR
• Repository Access: Ensure you have proper access to the repository before executing tasks
• Task Descriptions: Use descriptive task descriptions for better agent understanding
• Base Branch Selection: The --branch parameter sets the target/base branch for the PR, not the working branch. The agent always creates a new blackboxai/ branch to work on
• Branch Accessibility: Only specify --branch if that branch exists and is accessible. If unsure, omit it to use the current branch (when in a Git repo) or default branch
• Auto-Branch Creation: The system always auto-creates a new working branch with the blackboxai/ prefix when working with GitHub repositories
• Works with Any Repository: The username/repo format works for your own repositories, open-source projects, and any public GitHub repository you have access to
• Track Task Status: Use the task ID to check status directly in the CLI by asking “What’s the status of task [task-id]?”
• Monitor on Cloud: Visit cloud.blackbox.ai to view task execution logs, status updates, and pull requests in real-time

​

Key Features

• Terminal-Based Control: Manage remote agents without switching to a browser.
• Natural Language Commands: Issue tasks and queries conversationally.
• Real-Time Monitoring: Get live updates on task status and execution details.
• Seamless Integration: Connects directly to Blackbox Cloud for authenticated access.
• Tool Discovery: Dynamically list and utilize available remote tools.
• Task Orchestration: Enable the CLI agent to create or manage remote task(s), orchestrating them to achieve final goals through different tools available.

​

Benefits

• Terminal-Centric Workflow: Manage remote agents directly from your CLI without switching to a browser, streamlining development for command-line users.
• Natural Language Interaction: Issue complex tasks and queries using conversational commands, reducing the need for precise syntax or manual inputs.
• Real-Time Task Oversight: Monitor agent progress and execution details live in your terminal, enabling quick interventions and status checks.
• Dynamic Tool Utilization: Automatically discover and leverage available remote tools, expanding your CLI’s capabilities without additional setup.
• Agent Orchestration: Enable the CLI agent to manage and coordinate multiple remote agents, automating task delegation, parallel execution, and sub-task orchestration to achieve complex goals.
• Context Sharing: Seamlessly share remote agent task details with the CLI, enabling local improvements or continued development without context loss.

​

Use Cases

• Complex Feature Development: Build full-stack features autonomously via CLI commands, delegating code generation, testing, and integration to remote agents.
• Parallel Bug Fixes: Orchestrate simultaneous fixes across multiple repositories, executing and merging changes without manual intervention.
• Automated Code Reviews: Extend CLI capabilities with AI-powered reviews and merges on pull requests, enhancing git workflows.
• Real-Time Task Monitoring: Track and adjust remote agent progress in real-time, issuing follow-up commands for iterative development.
• Scalable Project Management: Coordinate subtasks across branches for large-scale refactoring or optimizations using orchestrated remote agents.

​

Next Steps