BRXCE MCP Server

Model Context Protocol (MCP) server for BRXCE workspace management.

Installation

From npm (Recommended for Claude Desktop users)

# Global installation
npm install -g @brxce/mcp-server

# Or use with npx (no installation needed)
npx @brxce/mcp-server

Claude Desktop Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "brxce-mcp": {
      "command": "npx",
      "args": ["-y", "@brxce/mcp-server"],
      "env": {
        "AUTH_TOKEN": "your_auth_token_here"
      }
    }
  }
}

Getting your AUTH_TOKEN:

1. Login to BRXCE: https://api.brxce.com/api/v1/auth/login
2. Copy the accessToken from the response
3. Add it to the config above

Optional environment variables:

• BACKEND_URL: Custom backend URL (default: Production)
• MCP_DEBUG: Enable debug logging (default: false)

Agent Skill (Best-Practice Playbook)

This package ships a portable agent skill (brxce-mcp) that documents the 89 BRXCE MCP tools, the 5 core principles, common workflows, and every known footgun. It works in both Claude Code and OpenClaw via the AgentSkills standard.

Install

# Auto-detect Claude Code and/or OpenClaw and install the skill there
npx @brxce/mcp-server install-skill

# Force a specific target
npx @brxce/mcp-server install-skill --target=claude
npx @brxce/mcp-server install-skill --target=openclaw
npx @brxce/mcp-server install-skill --target=both

# Overwrite an existing skill directory
npx @brxce/mcp-server install-skill --force

What it installs

• ~/.claude/skills/brxce-mcp/ (Claude Code)
• ~/.openclaw/workspace/skills/brxce-mcp/ (OpenClaw)

Each location receives a copy of SKILL.md plus the references/ directory (workflows, tool selection, footguns, error recovery).

After installing

Restart your agent so the skills cache picks up the new files:

• Claude Code: end the session and start a new one
• OpenClaw: openclaw gateway restart

The skill is version-locked with the MCP server it ships with. When you upgrade @brxce/mcp-server, re-run install-skill to refresh the docs.

Development

1. Build the server

pnpm build

2. Run with MCP Inspector (Recommended)

The easiest way to run the inspector with the config file:

# From project root
make mcp-inspect

This will:

• Build the MCP server
• Use inspector-config.json with AUTH_TOKEN included
• Open the browser with Inspector UI
• Test resources: user://me, workspace://{id}

First-time setup: If you don't have inspector-config.json:

1. Copy from example: cp inspector-config.example.json inspector-config.json
2. Add your AUTH_TOKEN (see "Getting an Auth Token" below)

Alternative methods:

Option A: Direct command with config file

npx @modelcontextprotocol/inspector --config inspector-config.json --server brxce-mcp

Option B: Using command line flags (not recommended)

npx @modelcontextprotocol/inspector \
  -e BACKEND_URL=http://localhost:3003/api/v1 \
  -e MCP_DEBUG=true \
  -e AUTH_TOKEN=your_token_here \
  node dist/index.js

Configuration

Environment Variables

Note: URL 설정은 @repo/config 패키지에서 중앙 관리됩니다. 자세한 환경 설정은 ENVIRONMENT.md 참조.

| 변수 | 설명 | 기본값 | |------|------|--------| | BRXCE_API_URL | API 엔드포인트 | (환경별 기본값) | | AUTH_TOKEN | JWT 인증 토큰 | (필수) | | REFRESH_TOKEN | JWT 리프레시 토큰 | (선택) | | MCP_DEBUG | 디버그 로깅 | false |

레거시 BACKEND_URL도 하위 호환성을 위해 지원됩니다.

Available Servers in Config

The inspector-config.json includes two pre-configured servers:

• brxce-mcp: For Dev-Local environment (port 3003)
• brxce-mcp-local: For Local environment (port 3000)

Resources

The MCP server exposes the following resources:

user://me

Returns current user information along with their accessible workspaces.

Example response:

{
  "user": {
    "id": "user-id",
    "email": "[email protected]",
    "username": "username",
    "name": "User Name",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  },
  "workspaces": [
    {
      "id": "b7d3f0c8-4b91-4c2e-9c19-6f02c123abcd",
      "name": "My Workspace",
      "slug": "my-workspace",
      "description": "Workspace description",
      "workspaceType": "TEAM",
      "planType": "FREE",
      "spaceId": 1,
      "userRole": "OWNER"
    }
  ]
}

workspace://{id}

Returns detailed information for a specific workspace.

Example:

• workspace://b7d3f0c8-4b91-4c2e-9c19-6f02c123abcd - Get details for workspace UUID b7d3f0c8-4b91-4c2e-9c19-6f02c123abcd
• workspace://3f2c1a44-1b2c-4d5e-8f90-abcdef123456 - Get details for workspace UUID 3f2c1a44-1b2c-4d5e-8f90-abcdef123456

Development

Project Structure

src/
├── config/
│   └── environment.ts       # Environment configuration
├── resources/
│   ├── user-resource.ts     # User + Workspaces resource
│   └── workspace-resource.ts # Individual workspace resource
├── services/
│   └── api-client.ts        # HTTP client for backend API
└── index.ts                 # MCP server entry point

Scripts

# Development mode (watch)
pnpm dev

# Build
pnpm build

# Type checking
pnpm check-types

# Linting
pnpm lint

Getting an Auth Token

To get a valid AUTH_TOKEN:

1. Using backend API:

# Login
curl -X POST http://localhost:3003/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password"
  }'

2. Copy the accessToken from the response

3. Update inspector-config.json:

{
  "mcpServers": {
    "brxce-mcp": {
      ...
      "env": {
        ...
        "AUTH_TOKEN": "paste-your-token-here"
      }
    }
  }
}

Troubleshooting

"Failed to fetch user" error

• Check if backend is running: curl http://localhost:3003/health
• Verify BACKEND_URL matches your backend port
• Ensure AUTH_TOKEN is valid and not expired

"Network error when calling" error

• Verify backend is accessible
• Check firewall/network settings
• Ensure the backend port in BACKEND_URL is correct

Inspector not connecting

• Make sure you've built the server first (pnpm build)
• Check that dist/index.js exists
• Verify the path in inspector-config.json is correct