workoflow-mcp

# Workoflow MCP Server MCP (Model Context Protocol) server that dynamically exposes your Workoflow organization's tools as native MCP tools to AI clients (Claude Code, Cursor, Windsurf, etc.). ## Features - **Native MCP tools**: Your organization's tools are exposed directly as MCP tools with full JSON schemas — no proxy layer - **Per-user dynamic tools**: Each user sees only their own tools, determined by their personal access token - **Token-based authentication**: Uses your personal access token from Workoflow - **Dual transport**: Supports both Streamable HTTP (`/mcp`) and SSE (`/sse`) - **OpenTelemetry tracing**: Integrated with Phoenix for observability ## Quick Start ### 1. Get Your Token 1. Log into Workoflow platform 2. Go to `/profile/` 3. Generate or copy your Personal Access Token ### 2. Configure Your AI Tool Add to your Claude Code MCP configuration (`~/.claude.json` or via `claude mcp add`): ```json { "mcpServers": { "workoflow": { "transport": "http", "url": "http://localhost:9006/mcp", "headers": { "X-Prompt-Token": "<your-personal-access-token>" } } } } ``` ### 3. Run the Server **Local development:** ```bash # Install dependencies pip install -r requirements.txt # Copy and configure environment cp .env.example .env # Edit .env with your settings # Run the server uvicorn workoflow_mcp.app:app --host 0.0.0.0 --port 9006 ``` **Docker:** ```bash docker build -t workoflow-mcp . docker run -p 9006:9000 --env-file .env workoflow-mcp ``` ## How It Works Your AI client connects to the MCP server and calls `tools/list`. The server extracts your token from the `X-Prompt-Token` header, fetches your available tools from the Workoflow platform API, and returns them as native MCP tools with full parameter schemas. When the AI calls a tool, the server proxies the execution to the platform API with your token. The platform enforces authorization — each user can only execute tools they have access to. ``` AI Tool (Claude Code/Cursor) │ │ MCP Protocol (Streamable HTTP + SSE) │ X-Prompt-Token header ▼ ┌─────────────────────┐ │ Workoflow MCP │ │ Server │ │ Port 9006 │ └─────────────────────┘ │ │ HTTP API │ X-Prompt-Token passthrough ▼ ┌─────────────────────┐ │ Workoflow Platform │ │ /api/mcp/tools │ │ /api/mcp/execute │ └─────────────────────┘ ``` ## Environment Variables | Variable | Description | Default | |----------|-------------|---------| | `WORKOFLOW_API_URL` | Platform API base URL | `http://localhost:8000` | | `TOOL_TYPES` | Comma-separated tool type filter | (all tools) | | `OTEL_SERVICE_NAME` | OpenTelemetry service name | `workoflow-mcp` | | `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP endpoint for tracing | (disabled) | ## Claude Desktop Extension A pre-built desktop extension (`.mcpb` bundle) is available in `desktop-extension/` for distributing the Workoflow MCP integration to Claude Desktop users via one-click install. ### How It Works The extension uses [mcp-remote](https://www.npmjs.com/package/mcp-remote) to bridge Claude Desktop's local stdio transport to the remote Workoflow MCP server at `https://workoflow-mcp.vcec.cloud/mcp`. On install, users are prompted for their Workoflow token which is stored securely in the OS keychain. ### Building the Extension ```bash cd desktop-extension # Install dependencies npm install --production # Package the .mcpb bundle npx @anthropic-ai/mcpb pack . ``` This produces `workoflow-1.0.0.mcpb` (bump the version in `manifest.json` before repacking a new release). ### Distributing to Your Team **As a Claude Desktop Team/Enterprise admin:** 1. Open Claude Desktop → **Settings → Extensions → Advanced settings** 2. Click **"Install Extension…"** and select the `.mcpb` file 3. Team members will see it available for one-click install **Or share directly:** send the `.mcpb` file via Slack, email, or internal file share — users double-click or drag it into Claude Desktop to install. ### Extension Structure | File | Purpose | |------|---------| | `manifest.json` | Extension metadata, server config, user config | | `server/index.js` | Thin wrapper delegating to mcp-remote | | `package.json` | Node.js package with mcp-remote dependency | | `icon.png` | 512×512 Workoflow logo | | `.mcpbignore` | Excludes tests/docs from the bundle | ## Security - **Per-user tool isolation**: Each `tools/list` call returns only the calling user's tools - **No stored credentials**: Server doesn't store tokens — extracted per-request from HTTP headers - **Per-request validation**: Token passed to platform API on every call; platform enforces authorization - **Zero shared state**: No session-to-token mapping, no server-side cache, no global tool registry - **Org-scoped**: Token determines which organization's tools you can access ## License Proprietary - Workoflow Platform