VibeControls MCP Server

Model Context Protocol (MCP) server for VibeControls — exposes 118 tools, 7 resources, and 7 prompts for AI assistant integration with the VibeControls developer control plane.

Quick Start

1. Install Dependencies

cd ~/products/vibecontrols/vibecontrols-mcp
bun install

2. Configure in Claude Code

Add to your project's .mcp.json (or ~/.claude/settings.json under mcpServers):

{
  "mcpServers": {
    "vibecontrols": {
      "type": "stdio",
      "command": "bun",
      "args": ["run", "~/products/vibecontrols/vibecontrols-mcp/src/index.ts"],
      "env": {
        "VIBECONTROLS_WORKSPACE_ENDPOINT": "http://localhost:4003/workspaces/graphql",
        "VIBECONTROLS_GLOBAL_ENDPOINT": "http://localhost:4000/global/graphql",
        "LOG_LEVEL": "error"
      }
    }
  }
}

3. Authenticate

On first use, Claude Code will need to authenticate with VibeControls:

1. Ask Claude to call vibecontrols_auth_login — returns a verification URL and user code immediately (non-blocking)
2. Open the URL in a browser and enter the code
3. Complete the login in the browser (email/password for the Burdenoff platform)
4. Ask Claude to call vibecontrols_auth_complete — checks if you've authorized and finishes the flow
5. If vibecontrols_auth_complete returns "pending", wait a moment and try again
6. Once authenticated, the MCP server automatically discovers your workspaces:
   • Single workspace: Auto-selected
   • Multiple workspaces: Returns a list — ask Claude to call vibecontrols_auth_select_workspace with the desired workspace ID and organization ID

Tokens are persisted at ~/.config/vibecontrols-mcp/auth.json (permissions 0o600) and auto-refresh before expiry.

4. Verify

Ask Claude: "Check my VibeControls auth status" — it will call vibecontrols_auth_status and show your authenticated state, workspace, and token expiry.

Prerequisites

The following services must be running for the MCP server to work:

| Service | Default URL | Purpose | |---------|-------------|---------| | Global Gateway | http://localhost:4000/global/graphql | Auth, workspace discovery | | Workspace Gateway | http://localhost:4003/workspaces/graphql | All vibecontrols operations | | global-auth-svc | (behind gateway) | OAuth device code flow | | wspace-vibecontrols-svc | (behind gateway) | Agents, vibes, sessions, etc. |

Start everything via make reset in ~/products/dev/ or start individual services manually.

Authentication Flow

┌─────────────┐   device code    ┌──────────────┐   verify code   ┌─────────┐
│  MCP Server  │ ──────────────> │ Global Gateway│ <────────────── │ Browser │
│  (stdio)     │                 │ (port 4000)   │                 │         │
└──────┬───────┘                 └───────┬───────┘                 └─────────┘
       │                                 │
       │  poll for token                 │  validate & issue
       │ <──────────────────────────────>│
       │                                 │
       │  access_token + refresh_token   │
       │ <───────────────────────────────│
       │                                 │
       │  MyWorkspaces query             │
       │ ───────────────────────────────>│
       │                                 │
       │  workspace list                 │
       │ <───────────────────────────────│
       │                                 │
       │  IssueWorkspaceToken            ┌──────────────────┐
       │ ───────────────────────────────>│ Workspace Gateway │
       │                                 │ (port 4003)      │
       │  workspace_token                │                   │
       │ <───────────────────────────────│                   │
       │                                 └──────────────────┘
       │
       │  All subsequent tool calls use both tokens:
       │  Authorization: Bearer <platform_token>
       │  X-Workspace-Authorization: Bearer <workspace_token>
       │  x-org-id: <organization_id>

Token auto-refresh: Both platform and workspace tokens are refreshed automatically 5 minutes before expiry.

Alternative auth: Set VIBECONTROLS_API_KEY or VIBECONTROLS_ACCESS_TOKEN env vars to skip the device code flow.

Tool Categories (118 tools)

| Category | Tools | Key Operations | |----------|-------|----------------| | Agents | 10 | CRUD, probe, health, plugins | | Vibes | 10 | CRUD, status, archive, hierarchy, search | | Sessions | 15 | CRUD, start/stop/restart, send input, web terminal, bulk ops | | Session Sharing | 8 | Share with users, share links, collaborators | | Notes | 8 | CRUD, search, pin/unpin | | Configuration | 5 | Scoped key-value settings | | Webhooks | 7 | CRUD, test, trigger | | Tunnels | 4 | CRUD for agent remote access | | Targets | 9 | CRUD, test, SSH scan, import, install agent | | Vibe Decks | 12 | Deck CRUD, button CRUD, execute | | Docs | 13 | Site CRUD, page CRUD, compile, publish, rollback | | Audit | 5 | List, get, stats, export, delete | | AI Events | 3 | List, create, recent | | UI Session | 3 | Get, save, clear state | | Auth | 6 | Login (start), complete, logout, status, workspaces, select workspace |

Resources (7)

| URI | Description | |-----|-------------| | vibecontrols://schema | GraphQL schema overview | | vibecontrols://config | Current MCP configuration and auth status | | vibecontrols://topology | Agent graph + active sessions + tunnels | | vibecontrols://sessions/active | All running sessions | | vibecontrols://notes/pinned | All pinned notes | | vibecontrols://audit/recent | Last 20 audit log entries | | vibecontrols://plugins | Installed plugins across agents |

Prompts (7)

| Prompt | Description | |--------|-------------| | vibecontrols-setup | Basic workspace setup (auth, agent, vibe, session) | | vibecontrols-session-workflow | Terminal session management guide | | vibecontrols-onboarding | Complete first-time onboarding | | vibecontrols-incident-response | Incident investigation workflow | | vibecontrols-deploy | Deployment using vibe decks | | vibecontrols-daily-standup | Activity summary for standups | | vibecontrols-runbook | Create documentation runbooks |

Development

bun install           # Install dependencies
bun run dev           # Dev server (stdio, hot reload)
bun run server:http   # HTTP transport mode
bun run sanity        # typecheck + lint + format + build
bun run build         # Production build

Environment Variables

See .env.example for all options. Key variables:

| Variable | Default | Description | |----------|---------|-------------| | VIBECONTROLS_WORKSPACE_ENDPOINT | http://localhost:4003/workspaces/graphql | Workspace gateway | | VIBECONTROLS_GLOBAL_ENDPOINT | http://localhost:4000/global/graphql | Global gateway | | VIBECONTROLS_API_KEY | — | API key auth (skips device code) | | VIBECONTROLS_ACCESS_TOKEN | — | Pre-set access token | | VIBECONTROLS_WORKSPACE_ID | — | Pre-select workspace | | VIBECONTROLS_ORGANIZATION_ID | — | Pre-select organization | | LOG_LEVEL | info | Logging level (error/warn/info/debug) |

Architecture

src/
├── index.ts                 # Entry point, CLI arg parsing, graceful shutdown
├── config/index.ts          # Zod-validated config, OIDC resolution
├── auth/index.ts            # OAuth2 device code, dual token management
├── graphql/
│   ├── client.ts            # Dual-endpoint GraphQL client with retry
│   └── operations.ts        # All GraphQL queries/mutations (80+ operations)
├── tools/                   # 15 tool modules (118 tools total)
│   ├── index.ts             # Tool registration hub
│   ├── agents.ts            # Agent management
│   ├── vibes.ts             # Project/vibe management
│   ├── sessions.ts          # Terminal sessions + bulk ops
│   ├── session-sharing.ts   # Session collaboration
│   ├── notes.ts             # Notes management
│   ├── configuration.ts     # Scoped configuration
│   ├── webhooks.ts          # Webhook management
│   ├── tunnels.ts           # Agent tunnels
│   ├── targets.ts           # Connection targets
│   ├── vibedecks.ts         # Command button grids
│   ├── docs.ts              # Documentation sites
│   ├── audit.ts             # Audit logging
│   ├── ai-events.ts         # AI tool events
│   ├── ui-session.ts        # UI state persistence
│   └── auth.ts              # Authentication tools
├── resources/index.ts       # 7 MCP resources
├── prompts/index.ts         # 7 MCP prompts
├── transports/              # stdio + HTTP transports
└── utils/                   # Shared helpers, logging

License

Proprietary - Copyright Burdenoff Consultancy Services Pvt. Ltd.