@braid-cloud/mcp

MCP stdio proxy for braid - bring your AI coding prompts to any tool that supports Model Context Protocol.

What It Does

This package bridges tools that only support stdio-based MCP (like Zed, Claude Desktop) to braid's hosted MCP server. Your AI assistant gets access to your team's prompts, skills, and guidelines in real-time.

Your Tool (Zed, Claude Desktop, etc.)
    │ stdio
    ▼
braid-mcp (this package)
    │ HTTPS
    ▼
braid Cloud

Quick Start

# 1. Install
npm install -g @braid-cloud/mcp

# 2. Create a Personal Access Token (PAT) at https://app.braid.cloud/settings/tokens

# 3. Run (beginner-safe command)
BRAID_TOKEN=br_xxx braid-mcp

# Advanced: custom MCP URL
BRAID_TOKEN=br_xxx BRAID_MCP_URL=https://custom.braid.cloud/api/mcp braid-mcp

Tool Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "braid": {
      "command": "braid-mcp",
      "env": {
        "BRAID_TOKEN": "br_your_token_here"
      }
    }
  }
}

Zed

Add to your Zed settings:

{
  "context_servers": {
    "braid": {
      "command": {
        "path": "braid-mcp",
        "args": [],
        "env": {
          "BRAID_TOKEN": "br_your_token_here"
        }
      }
    }
  }
}

Other MCP Clients

Any tool supporting MCP stdio transport works. Run braid-mcp as the command with BRAID_TOKEN in the environment.

Context note: BRAID_TOKEN is MCP runtime auth. The CLI package uses BRAID_API_KEY for CLI auth flows.

You can also use a package runner instead of a global install:

| Runner | Command | | ------ | --------------------------- | | npx | npx -y @braid-cloud/mcp | | pnpm | pnpm dlx @braid-cloud/mcp | | yarn | yarn dlx @braid-cloud/mcp | | bunx | bunx @braid-cloud/mcp |

Project Configuration

For team workflows, configure braid per-repository instead of per-user.

braid.json (commit to git)

Shared team settings:

{
  "$schema": "https://braid.cloud/schemas/config.json",
  "org": "my-org",
  "orgProjects": ["proj_frontend", "proj_shared"],
  "profile": "web-development",
  "includeUserGlobal": true,
  "includeOrgGlobal": true
}

braid.user.json (add to .gitignore)

Personal overrides and token:

{
  "token": "br_your_personal_token",
  "personalProjects": ["proj_my_experiments"]
}

The proxy searches upward from the current directory to find these files.

All Config Options

| Field | Type | Description | | ------------------- | -------- | ------------------------------------------------------------------ | | token | string | Personal Access Token (PAT, user config only) | | serverUrl | string | Full MCP endpoint URL (default: https://app.braid.cloud/api/mcp) | | profile | string | Named profile to use | | org | string | Organization to scope searches | | orgProjects | string[] | Org project IDs to include | | personalProjects | string[] | Personal project IDs to include | | includeUserGlobal | boolean | Include user's global prompts (default: true) | | includeOrgGlobal | boolean | Include org's global prompts (default: true if org) | | disableInit | boolean | Disable exposing braid_init (default: false) |

Config Resolution

1. braid.json (base config, searched upward from cwd)
2. braid.user.json (overrides base, searched upward from cwd)
3. BRAID_TOKEN env var (MCP runtime fallback when no token in config)
4. BRAID_MCP_URL env var (used when serverUrl is not set in config; use full endpoint URL)

Environment Variables

| Variable | Required | Description | | ------------------------------- | -------- | ------------------------------------------------------------------------------- | | BRAID_TOKEN | Yes* | Personal Access Token (PAT) for MCP runtime | | BRAID_MCP_URL | No | Custom full MCP endpoint URL (for example https://custom.braid.cloud/api/mcp) | | BRAID_ALLOW_UNTRUSTED_MCP_URL | No | Set true to allow non-*.braid.cloud MCP hosts | | BRAID_CONFIG_DIR | No | Starting directory for config file search |

*Can also be set in braid.user.json

Available Tools

The proxy exposes these MCP tools to your AI assistant:

| Tool | Description | | ------------------- | -------------------------------------------------------------------------------------------- | | braid_init | Load default rules and skill triggers for the session | | get_skills | Fetch skills by exact name (from braid_init triggers) | | braid_heartbeat | Lightweight skill reminder; can include active workflow context when sessionId is provided | | save_rule | Create a new rule or skill | | update_rule | Update an existing rule by ID | | get_references | Fetch attached files for a rule | | discover_projects | List available projects | | discover_scope | Show current context and scope resolution |

Typical flow: braid_init (start of conversation) -> get_skills (when a skill is triggered) -> braid_heartbeat (mid-conversation reminder).

If disableInit is true in config, braid_init is not exposed and the workflow is fully manual.

Local CLI Tools (Consolidated)

To avoid tool-list bloat, local CLI management uses one root tool per domain with a required command argument. This makes MCP automation predictable: your agent picks a local tool, sends a small JSON payload, and braid runs the matching CLI command.

| Tool | Common commands | Command-specific requirements | | ---------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | cli_projects | list, get, create, update, remove | remove requires yes=true | | cli_rules | list (plus rule CRUD/sync commands) | command-specific fields vary by action | | cli_profiles | list, get, create, update, remove, set-default | remove requires yes=true; set-default requires id or name | | cli_references | list, get, create, update, remove, reorder | list/create/reorder require ruleId; remove requires yes=true; reorder requires orderedIds[] | | cli_skills | list, install, update, remove | install requires profile or orgProjects[] or personalProjects[]; remove requires skill or all=true | | cli_auth | status, set, logout | set requires token | | cli_scope | set | requires organization and source; if source=profile, requires profile | | cli_mcp | status, add, remove | add/remove require tool and yes=true | | cli_workflows | list, start, progress, active, complete, fail, cancel | start requires sessionId + flowId; progress/complete/fail/cancel require executionId; active requires sessionId |

Automation quick examples (direct MCP tool call payloads):

• Set auth token via braid:cli_auth

{ "command": "set", "token": "br_xxx", "noScope": true }

• List available projects via braid:cli_projects

{ "command": "list" }

• Update project scope via braid:cli_scope

{
  "command": "set",
  "file": "project",
  "organization": "organization",
  "source": "manual",
  "projects": ["proj_frontend", "proj_shared"],
  "includeUserGlobal": true,
  "includeOrgGlobal": true
}

Examples:

{ "command": "list" }

{ "command": "set", "token": "br_xxx", "noScope": true }

{ "command": "remove", "tool": "claude-code", "yes": true }

Machine Templates

Use these as direct MCP tool-call payloads.

cli_projects

{ "command": "list" }

cli_rules

{ "command": "list" }

{
  "command": "list",
  "orgProjects": ["proj_123"],
  "includeUserGlobal": true,
  "includeOrgGlobal": false
}

cli_skills

{ "command": "list", "profile": "default" }

{ "command": "install", "profile": "default", "yes": true }

{ "command": "update", "yes": true }

{ "command": "remove", "skill": "my-skill", "yes": true }

{ "command": "remove", "all": true, "yes": true }

cli_auth

{ "command": "status" }

{ "command": "set", "token": "br_xxx", "noScope": true }

{ "command": "logout" }

cli_scope

{
  "command": "set",
  "file": "user",
  "organization": "personal",
  "source": "profile",
  "profile": "default"
}

{
  "command": "set",
  "file": "user",
  "organization": "organization",
  "source": "manual",
  "projects": ["proj_123"],
  "includeUserGlobal": true,
  "includeOrgGlobal": true
}

cli_mcp

{ "command": "status" }

{ "command": "add", "tool": "claude-code", "yes": true }

{ "command": "remove", "tool": "claude-code", "yes": true }

cli_workflows

{ "command": "list" }

{
  "command": "start",
  "sessionId": "cli_sess_123",
  "flowId": "flow_123",
  "currentStepLabel": "input"
}

{
  "command": "progress",
  "executionId": "exec_123",
  "currentNodeId": "node_2",
  "currentStepLabel": "prompt",
  "metadata": { "attempt": 1 }
}

{ "command": "active", "sessionId": "cli_sess_123" }

Reference: docs/workflows/local-execution-session-state.md.

Programmatic Usage

import { Effect } from "effect";
import { createProxyServer } from "@braid-cloud/mcp";

const { server, client, close } = await Effect.runPromise(
  createProxyServer({
    token: "br_your_token_here",
    serverUrl: "https://app.braid.cloud/api/mcp", // optional
    repoContext: {
      profile: "my-profile",
      org: "my-org",
      orgProjects: ["proj_123"],
      includeUserGlobal: true,
    },
  }),
);

// When done:
await close();

Related

• @braid-cloud/cli - Install prompts as local skill files (works offline)
• braid Website - Learn more about braid and sign up for an account.

License

Proprietary - all rights reserved.