@dobbyai/mcp-external

Dobby MCP Server

Connect to Dobby AI Platform from Claude Desktop, Cursor, Windsurf, VS Code, and any MCP-compatible client.

🚀 Quick Start

Option 1: Interactive Setup (Recommended)

npx @dobbyai/mcp-external --setup

This will guide you through connecting Dobby to your preferred AI tools.

Option 2: Manual Setup

• Get your API credentials from Dobby Dashboard
• Add to your MCP client config:

{
  "mcpServers": {
    "dobby": {
      "command": "npx",
      "args": ["-y", "@dobbyai/mcp-external"],
      "env": {
        "DOBBY_API_URL": "https://app.dobby.ai",
        "DOBBY_API_KEY": "your-api-key",
        "DOBBY_TENANT_ID": "your-tenant-id"
      }
    }
  }
}

📱 Supported Clients

Client	Status	Setup Command
Claude Desktop	✅ Full Support	npx @dobbyai/mcp-external --setup
Cursor	✅ Full Support	npx @dobbyai/mcp-external --setup
Windsurf	✅ Full Support	npx @dobbyai/mcp-external --setup
VS Code (Cline)	✅ Full Support	Manual config
VS Code (Continue)	✅ Full Support	Manual config
Any MCP Client	✅ STDIO Mode	Manual config

🔧 Available Tools (12 Tools)

Task Management (6 tools)

Tool	Description	Example
create_task	Create a new task for AI agents	create_task(title: "Add dark mode", priority: "high")
list_tasks	List tasks with filters	list_tasks(status: "pending", limit: 10)
get_task	Get detailed task information	get_task(task_id: "task-abc123")
update_task	Update task status or priority	update_task(task_id: "...", status: "in_progress")
get_task_timeline	Get activity history for a task	get_task_timeline(task_id: "...")
cancel_task	Cancel a running task	cancel_task(task_id: "...")

Conversation (2 tools)

Tool	Description	Example
get_messages	Get conversation for a task	get_messages(task_id: "...", limit: 20)
send_message	Send a message to task conversation	send_message(task_id: "...", content: "Please add tests")

Approvals - Human-in-the-Loop (4 tools)

Tool	Description	Example
get_pending_approvals	List approvals waiting for you	get_pending_approvals()
approve_task	Approve a pending request (auto-merges PR)	approve_task(approval_id: "...", note: "LGTM")
reject_task	Reject with feedback (agent retries automatically)	reject_task(approval_id: "...", reason: "Need tests")
request_changes	Request specific modifications	request_changes(approval_id: "...", changes: "...")

🔄 Approval Flow

The Dobby MCP Server supports a complete Human-in-the-Loop workflow:

┌─────────────────────────────────────────────────────────────────┐
│                    APPROVAL WORKFLOW                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  1. Agent completes work → Creates PR → Requests approval        │
│                                                                  │
│  2. User receives notification via get_pending_approvals         │
│                                                                  │
│  3. User reviews and decides:                                    │
│                                                                  │
│     ┌─────────────────┐     ┌─────────────────┐                 │
│     │  approve_task   │     │   reject_task   │                 │
│     │                 │     │                 │                 │
│     │  ✅ Auto-merge  │     │  🔁 Auto-retry  │                 │
│     │     PR          │     │  with feedback  │                 │
│     └────────┬────────┘     └────────┬────────┘                 │
│              │                       │                           │
│              ▼                       ▼                           │
│     ┌─────────────────┐     ┌─────────────────┐                 │
│     │ Task Completed  │     │ Agent Addresses │                 │
│     │ 🎉              │     │ Feedback & ...  │──► Back to 1    │
│     └─────────────────┘     └─────────────────┘                 │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Approve Flow

• User calls approve_task(approval_id, note?)
• Agent automatically merges the PR
• Task status changes to completed
• User gets confirmation via get_task_timeline

Reject Flow (with automatic retry)

• User calls reject_task(approval_id, reason)
• Agent receives feedback
• Agent re-analyzes and addresses the feedback
• Agent creates new implementation
• New approval is requested
• User reviews again

📊 Task Timeline

Track every action on a task with get_task_timeline:

📊 Timeline for Task task-abc123

🆕 task created (User)
   2/2/2026, 10:00:00 AM

📋 plan created (DevCoordinator)
   2/2/2026, 10:00:05 AM

▶️ subtask started (dobby-frontend-agent)
   2/2/2026, 10:00:10 AM

🎨 frontend code generated (FrontendDeveloper)
   2/2/2026, 10:01:30 AM

📝 pr created (FrontendDeveloper)
   PR #42
   2/2/2026, 10:01:45 AM

⏳ approval requested (DevCoordinator)
   2/2/2026, 10:01:50 AM

✅ approval approved (User)
   2/2/2026, 10:05:00 AM

🚀 agent continuation triggered (system)
   2/2/2026, 10:05:01 AM

🔀 pr merged (DevCoordinator)
   PR #42
   2/2/2026, 10:05:10 AM

🎉 continuation after approval completed (DevCoordinator)
   2/2/2026, 10:05:15 AM

📚 Resources

Access data directly via MCP resources:

tasks://list              # All tasks
tasks://pending           # Pending tasks
tasks://in-progress       # In-progress tasks
tasks://completed         # Completed tasks
tasks://{task_id}         # Specific task details
tasks://{task_id}/messages # Task conversation
approvals://pending       # Pending approvals

💬 Prompts (Slash Commands)

Command	Description
/create-feature	Guided feature creation
/fix-bug	Create bug fix task
/check-approvals	Review pending approvals
/task-status	Get task status summary
/review-pr	Review a task's PR

🖥️ Client-Specific Setup

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "dobby": {
      "command": "npx",
      "args": ["-y", "@dobbyai/mcp-external"],
      "env": {
        "DOBBY_API_URL": "https://app.dobby.ai",
        "DOBBY_API_KEY": "dk_your_api_key",
        "DOBBY_TENANT_ID": "your-tenant-id"
      }
    }
  }
}

Cursor

Settings → MCP → Add Server:

{
  "dobby": {
    "command": "npx",
    "args": ["-y", "@dobbyai/mcp-external"],
    "env": {
      "DOBBY_API_URL": "https://app.dobby.ai",
      "DOBBY_API_KEY": "dk_your_api_key",
      "DOBBY_TENANT_ID": "your-tenant-id"
    }
  }
}

Windsurf

File: ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "dobby": {
      "command": "npx",
      "args": ["-y", "@dobbyai/mcp-external"],
      "env": {
        "DOBBY_API_URL": "https://app.dobby.ai",
        "DOBBY_API_KEY": "dk_your_api_key",
        "DOBBY_TENANT_ID": "your-tenant-id"
      }
    }
  }
}

VS Code with Cline

Command Palette → "Cline: Open MCP Settings" → Add:

{
  "mcpServers": {
    "dobby": {
      "command": "npx",
      "args": ["-y", "@dobbyai/mcp-external"],
      "env": {
        "DOBBY_API_URL": "https://app.dobby.ai",
        "DOBBY_API_KEY": "dk_your_api_key",
        "DOBBY_TENANT_ID": "your-tenant-id"
      }
    }
  }
}

🔐 Environment Variables

Variable	Required	Description
DOBBY_API_URL	Yes	Dobby API URL (default: https://app.dobby.ai)
DOBBY_API_KEY	Yes	Your Dobby API key
DOBBY_TENANT_ID	Yes	Your workspace/tenant ID
DOBBY_USER_ID	No	User ID for messages
DOBBY_USER_NAME	No	Display name for messages

📖 Usage Examples

Create a Feature Task

You: Create a task to add dark mode to the settings page

Claude: [Uses create_task tool]
        ✅ Task created: task-abc123
        Title: Add dark mode to settings page
        Priority: medium

        The AI agents will start working on it soon.

Check Approvals

You: Check my pending approvals

Claude: [Uses get_pending_approvals]

        🔔 You have 2 pending approvals:

        1. 📝 PR CREATE - Add user authentication
           ID: approval-xyz789
           Waiting: 5 minutes

        2. 🔀 PR MERGE - Fix login bug
           ID: approval-abc456
           Waiting: 1 hour

        Which one would you like to review?

Approve a PR (Auto-Merge)

You: Approve approval-xyz789 with note "looks good"

Claude: [Uses approve_task]
        ✅ **Approved!** approval-xyz789

        Note: "looks good"

        🔀 The agent is now merging the PR automatically.
        Use `get_task_timeline` to track progress.

Reject with Feedback (Auto-Retry)

You: Reject approval-abc456 because it needs unit tests

Claude: [Uses reject_task]
        ❌ **Rejected!** approval-abc456

        💬 Feedback: "needs unit tests"

        🔁 The agent is now retrying and will address your feedback.
        Use `get_task_timeline` to track progress.

Cancel Running Task

You: Cancel task-def789, it's taking too long

Claude: [Uses cancel_task]
        🛑 Task task-def789 execution cancelled successfully.

        The task status has been reverted to pending.

View Task Timeline

You: Show me the timeline for task-abc123

Claude: [Uses get_task_timeline]

        📊 Timeline for Task task-abc123

        🆕 **task created** (User)
           2/2/2026, 10:00:00 AM

        📋 **plan created** (DevCoordinator)
           2/2/2026, 10:00:05 AM

        🎨 **frontend code generated** (FrontendDeveloper)
           2/2/2026, 10:01:30 AM

        📝 **pr created** PR #42
           2/2/2026, 10:01:45 AM

        ✅ **approval approved**
           2/2/2026, 10:05:00 AM

        🔀 **pr merged** PR #42
           2/2/2026, 10:05:10 AM

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     MCP Client                                   │
│         (Claude Desktop, Cursor, Windsurf, etc.)                │
└──────────────────────────┬──────────────────────────────────────┘
                           │ MCP Protocol (STDIO)
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                   Dobby MCP Server                               │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │ Tools           │ Resources       │ Prompts                 ││
│  │ - create_task   │ - tasks://      │ - /create-feature       ││
│  │ - list_tasks    │ - approvals://  │ - /fix-bug              ││
│  │ - get_task      │                 │ - /check-approvals      ││
│  │ - update_task   │                 │ - /task-status          ││
│  │ - get_timeline  │                 │ - /review-pr            ││
│  │ - cancel_task   │                 │                         ││
│  │ - get_messages  │                 │                         ││
│  │ - send_message  │                 │                         ││
│  │ - get_pending   │                 │                         ││
│  │ - approve_task  │                 │                         ││
│  │ - reject_task   │                 │                         ││
│  │ - req_changes   │                 │                         ││
│  └─────────────────────────────────────────────────────────────┘│
│                              │                                   │
│                    DobbyClient (API)                             │
└──────────────────────────────┬──────────────────────────────────┘
                               │ HTTPS
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Dobby API (Next.js)                          │
│  /api/dobby/tasks        - Task CRUD                             │
│  /api/dobby/tasks/[id]/execute - Execute/Cancel task            │
│  /api/dobby/tasks/[id]/conversation - Messages                  │
│  /api/dobby/approvals    - Approval workflow                    │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                  Dobby Python API (FastAPI)                     │
│  POST /api/v1/tasks/{id}/execute   - Start agent execution      │
│  POST /api/v1/tasks/{id}/cancel    - Cancel execution           │
│  GET  /api/v1/runs/{id}/status     - Get run status             │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                    AI Agents (Dobby)                            │
│  ┌──────────────┐                                               │
│  │ Chief Agent  │ ─► Analyzes tasks, routes to coordinators     │
│  └──────┬───────┘                                               │
│         │                                                        │
│  ┌──────▼───────┐                                               │
│  │ DevCoordinator│ ─► Manages development workflow              │
│  └──────┬───────┘                                               │
│         │                                                        │
│  ┌──────▼───────────────────────────────────────┐              │
│  │ Workers                                       │              │
│  │ - FrontendDeveloper (React, TypeScript)      │              │
│  │ - BackendDeveloper (Python, FastAPI)         │              │
│  │ - TestWriter (Unit tests)                    │              │
│  │ - CodeReviewer (PR review)                   │              │
│  │ - DevOpsWorker (CI/CD, PR merge)             │              │
│  └───────────────────────────────────────────────┘              │
└─────────────────────────────────────────────────────────────────┘

🛠️ Development

# Clone the repo
git clone https://github.com/gil-dataopsvalley/repo-dobby.git
cd repo-dobby/mcp/external

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build
npm run build

# Run tests
npm test

Local Testing

# Set environment variables
export DOBBY_API_URL=http://localhost:3000
export DOBBY_API_KEY=dev-key
export DOBBY_TENANT_ID=your-tenant-id

# Run the server
npm run dev

📝 Changelog

v1.2.0 (2026-02-02)

• NEW: get_task_timeline tool - View all activity on a task
• NEW: cancel_task tool - Stop running task executions
• IMPROVED: approve_task now triggers automatic PR merge
• IMPROVED: reject_task now triggers automatic agent retry with feedback
• IMPROVED: Better response messages with action hints

v1.1.0 (2026-01-31)

• Added VS Code support (Cline, Continue)
• Added Windsurf connector
• Fixed approval endpoint compatibility

v1.0.0 (2026-01-29)

• Initial release
• 10 tools for task management, messaging, and approvals
• 7 resources for direct data access
• 5 slash command prompts
• Support for Claude Desktop and Cursor

📄 License

MIT © Dobby AI Platform