@orchestrator/mcp-server

> MCP server for Orchestrator - thin client forwarding to REST API

Overview

This package provides an MCP (Model Context Protocol) server that exposes Orchestrator functionality to Claude Code and other MCP-compatible clients.

Architecture: This is a thin client that forwards all requests to the Orchestrator REST API. It contains NO business logic, only request transformation and error handling.

Installation

$3

``bash
npm install -g @orchestrator/mcp-server
`

$3

`bash
npm install @orchestrator/mcp-server
`

Configuration

$3

1. REST API Server Running: The MCP server requires the Orchestrator REST API to be running.

`bash
# Start API server (in main orchestrator project)
docker-compose up -d
# OR
npm start
`

2. API Key: Generate an API key using the CLI:

`bash
orchestrator auth generate
`

This creates ~/.orchestrator/config.json with your API key.

$3

Add to your Claude Code config (.mcp.json or Claude settings):

`json
{
"mcpServers": {
"orchestrator": {
"command": "orchestrator-mcp-server"
}
}
}
`

$3

- MCP_DEBUG=true - Enable debug logging
- ORCHESTRATOR_API_URL - Override API URL (default: http://localhost:3000)

Available Tools

$3

- getStatus - Get workflow status
- advancePhase - Advance workflow to next phase
- approveAction - Approve pending action
- getContext (v2) - Get workflow context and available actions
- executeAction (v2) - Execute deterministic action

$3

- detectWorkflow - Detect workflow type from prompt
- validateArtifact - Validate generated artifacts
- createCheckpoint - Create git checkpoint

$3

- getNextAction - Get next pending action
- setPendingAction - Set pending action for agent invocation
- clearPendingAction - Clear pending action
- approveAction - Approve action requiring human approval

Architecture

`
Claude Code
↓
MCP Server (thin client)
↓
REST API (business logic)
↓
Domain/Application/Infrastructure Layers
`

Key Principles:

1. No Business Logic: All logic resides in REST API
2. Stateless: No state stored in MCP server
3. Simple Transformation: Request → API Call → Response
4. Error Forwarding: API errors forwarded to Claude

Development

$3

`bash
npm run build
`

$3

`bash
npm test
`

$3

`bash


With debug logging


MCP_DEBUG=true npm start
`

Troubleshooting

$3

1. Check if REST API is running:
`bash
curl http://localhost:3000/api/v1/health
`

2. Check if API key is configured:
`bash
cat ~/.orchestrator/config.json
`

3. Regenerate API key if needed:
`bash
orchestrator auth generate
`

$3

Run:
`bash
orchestrator auth generate
`

$3

1. Ensure global installation:
`bash
npm list -g @orchestrator/mcp-server
``

2. Restart Claude Code after installing

3. Check Claude Code logs for MCP connection errors

Version Compatibility

| MCP Server | Orchestrator CLI | REST API |
|------------|------------------|----------|
| 0.9.x | >= 0.9.0 | >= 0.9.0 |
| 1.0.x | >= 1.0.0 | >= 1.0.0 |

License

MIT

Support

- Documentation
- GitHub Issues
- Discord Community