> ## Documentation Index > Fetch the complete documentation index at: https://docs.blackbox.ai/llms.txt > Use this file to discover all available pages before exploring further. # BLACKBOX AI MCP > Integrate with remote agents via Model Context Protocol (MCP) using Blackbox CLI for seamless terminal-based task management and execution. ## Overview BLACKBOX AI MCP (Model Context Protocol) enables direct interaction with remote agents through the Blackbox CLI in your terminal. This integration allows you to assign tasks, monitor progress, retrieve execution details, and control remote agents effortlessly from the command line. By connecting your CLI to the Blackbox Cloud MCP server, you gain the full power of remote agents without leaving your development environment. Start Task The MCP integration enables the CLI agent to orchestrate multiple sub-tasks and parallel tasks, including creation, stopping, merging changes, and coordinating remote agents to achieve final goals. This feature is ideal for developers who prefer terminal workflows, enabling natural language commands to manage tasks, query agent capabilities, and execute complex operations on remote repositories. ## Getting Started To set up MCP integration with Blackbox Cloud, follow these steps: 1. **Access MCP Token Section**\ Navigate to [cloud.blackbox.ai](https://cloud.blackbox.ai), log in, and go to your profile settings. Locate the "MCP Token" section. 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. Generate Token 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. Token Command View 4. **Connect MCP Server in Terminal**\ Open your terminal and run the command you have copied from MCP Setup Command or the following command: ``` blackbox mcp add remote-code https://cloud.blackbox.ai/api/mcp -t http -H "Authorization: Bearer " ``` Replace `` with your actual token. Add MCP Command 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. MCP Connected With the MCP server connected, you can now interact with remote agents directly from your CLI. ## How It Works Once connected, use tools or issue natural language commands in the Blackbox CLI to control remote agents. The MCP integration supports querying tools, managing tasks, executing operations, and much more seamlessly. * **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. Ask Capabilities * **View Existing Tasks**\ Query your tasks by saying: `"Get all my tasks"` to retrieve a list of current and past tasks. Get 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. Start Task You can verify the same via Blackbox Cloud UI in browser. View Task UI * **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. This hands-free interaction brings the power of remote agents directly into your terminal workflow. ## Using /remote Commands The `/remote` command provides a streamlined way to execute tasks on your GitHub repositories directly from the Blackbox CLI. This slash command syntax offers a quick alternative to natural language task creation. ##### Command Syntax ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} /remote [] [--branch ] ``` **Parameters:** * ``: Description of the task you want to execute * `` (optional): Repository identifier (see formats below). If omitted and you're inside a Git repository, the current repository is automatically used * `--branch ` (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 When you run the `/remote` command from within a Git repository, Blackbox CLI automatically detects and uses your current repository context. This provides a seamless experience for working on local repositories. **How It Works:** 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 **Examples from Within a Git Repository:** ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} # Inside /path/to/my-project (a Git repo on branch 'develop') /remote add authentication feature ``` This will: * Use the current repository (my-project) * Create a new `blackboxai/` branch * Raise a PR to `develop` (your current branch) ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} # Override the base branch while using current repo /remote fix bug --branch main ``` This will: * Use the current repository * Create a new `blackboxai/` branch * Raise a PR to `main` (specified branch, not your current branch) ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} # Work on a completely different repository /remote add tests username/other-repo --branch main ``` This will: * 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` **When NOT Inside a Git Repository:** If you run `/remote` without specifying a repository and you're NOT inside a Git repository, the task will execute in a sandbox environment without GitHub integration: ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} # Not inside any Git repository /remote create a simple calculator app ``` This will: * 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 **Use Cases for Sandbox Execution:** * Quick prototyping and testing * Creating standalone scripts or utilities * Experimenting with code without repository setup * Learning and exploration tasks **Benefits:** * **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 When you need to specify a repository explicitly (or when not inside a Git repository), you can use these formats: 1. **Username/Repository Format**: ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} /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: ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} /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`): ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} /remote implement feature --repo-url https://github.com/username/repository ``` 3. **Natural Language** (repository mentioned in task description): ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} /remote add stripe integration to username/my-web-app repository ``` ##### Branch Behavior The `--branch` parameter specifies the **base branch** for your pull request, not the working branch name: * **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`) **Example:** ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} /remote add feature username/repo --branch develop ``` This will: 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) **Note:** If you specify a branch that doesn't exist or you don't have access to, remove the `--branch` parameter to use the default branch instead. ##### Usage Examples **Working Inside a Git Repository (Automatic Context):** ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} # 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 ``` **Specifying a Different Repository:** ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} # 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 ``` **Using Full Repository URL:** ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} /remote implement user dashboard --repo-url https://github.com/username/my-project --branch feature/dashboard ``` **Natural Language with Repository:** ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} /remote add payment processing to the /e-commerce-backend repository on main branch ``` ##### Alternative Syntax You can also specify the branch inline without the `--branch` flag: ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} /remote add dark mode support username/my-app main ``` Or combine repository URL with branch: ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} /remote implement API endpoints --repo-url https://github.com/username/api-service main ``` This will execute the task on the `main` branch if it exists, or create a new branch if it doesn't. ##### 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](https://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](https://cloud.blackbox.ai) - View all PRs and task results ##### Monitoring Tasks on Blackbox Cloud After executing a `/remote` command, you can monitor and manage your tasks in multiple ways: ##### Via Blackbox Cloud Web Interface Visit [cloud.blackbox.ai](https://cloud.blackbox.ai) to access: * **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 You can also check task status directly in the CLI using the task ID: **Get Task Status:** ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} What's the status of task [task-id]? ``` The CLI will automatically query the task status and provide you with: * Current execution status * Progress updates * Any errors or issues * Completion status * Link to the pull request (if completed) **Example:** ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}} # 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? ``` The CLI maintains context of your tasks and can provide real-time status updates without needing to visit the web interface. ##### Tips * **Work Locally**: When inside a Git repository, simply run `/remote ` 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](https://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 Explore related Blackbox Cloud features to expand your remote development capabilities: Learn about the full remote agent platform. Dive deeper into terminal-native development. Run multiple agents in parallel. Manage tasks via Slack. MCP integration transforms your CLI into a powerful hub for remote agent control, streamlining workflows and enhancing productivity.