swf-monitor/docs/MCP_CLIENTS.md

0001 # MCP Client Setup
0002
0003 This document covers client configuration for the SWF Monitor MCP server. The
0004 main integration overview is [MCP.md](MCP.md), and the full tool catalog is
0005 [MCP_TOOL_REFERENCE.md](MCP_TOOL_REFERENCE.md).
0006
0007 ## Client Configuration
0008
0009 ### Claude Desktop
0010
0011 For clients running on swf-testbed, add to `claude_desktop_config.json`:
0012
0013 ```json
0014 {
0015   "mcpServers": {
0016     "swf-monitor": {
0017       "url": "http://127.0.0.1:8001/swf-monitor/mcp/",
0018       "transport": "http"
0019     }
0020   }
0021 }
0022 ```
0023
0024 ### Claude Code
0025
0026 Add via `/mcp add` or create `.mcp.json` in project:
0027
0028 ```json
0029 {
0030   "mcpServers": {
0031     "swf-monitor": {
0032       "type": "http",
0033       "url": "http://127.0.0.1:8001/swf-monitor/mcp/"
0034     }
0035   }
0036 }
0037 ```
0038
0039 ## Authentication
0040
0041 The operational MCP clients on swf-testbed are local clients: Claude Code,
0042 the PanDA Mattermost bot, the testbed bot, scripts, and the watchdog. They use
0043 the loopback ASGI endpoint and do not require OAuth.
0044
0045 The public Apache path still exists, but remote Claude.ai GET/SSE streaming is
0046 not an operational dependency and should not be treated as supported by the
0047 current deployment. If remote MCP access is reintroduced, require OAuth 2.1
0048 and revalidate the transport lifecycle under load before enabling it.
0049
0050 **Configuration (production):**
0051 ```bash
0052 # In .env or environment
0053 AUTH0_DOMAIN=your-tenant.us.auth0.com
0054 AUTH0_CLIENT_ID=your-client-id
0055 AUTH0_CLIENT_SECRET=your-client-secret
0056 AUTH0_API_IDENTIFIER=https://your-server/swf-monitor/mcp
0057 ```
0058
0059 Leave `AUTH0_DOMAIN` empty to disable OAuth. Do not expose unauthenticated
0060 remote MCP access.
0061
0062 ---
0063
0064 ### Claude Code Settings Example
0065
0066 Full `~/.claude/settings.json` with swf-monitor MCP server, permissions, and status line:
0067
0068 ```json
0069 {
0070   "mcpServers": {
0071     "swf-monitor": {
0072       "type": "http",
0073       "url": "http://127.0.0.1:8001/swf-monitor/mcp/"
0074     }
0075   },
0076   "statusLine": {
0077     "type": "command",
0078     "command": "~/.claude/statusline.sh"
0079   },
0080   "permissions": {
0081     "allow": [
0082       "Bash(ls:*)",
0083       "Bash(wc:*)",
0084       "Bash(grep:*)",
0085       "mcp__swf-monitor__get_server_instructions",
0086       "mcp__swf-monitor__swf_list_agents",
0087       "mcp__swf-monitor__swf_get_agent",
0088       "mcp__swf-monitor__swf_list_workflow_executions",
0089       "mcp__swf-monitor__swf_get_workflow_execution",
0090       "mcp__swf-monitor__swf_list_logs",
0091       "mcp__swf-monitor__swf_get_system_state",
0092       "WebSearch",
0093       "WebFetch"
0094     ],
0095     "defaultMode": "default"
0096   },
0097   "alwaysThinkingEnabled": true
0098 }
0099 ```
0100
0101 **Status line script** (`~/.claude/statusline.sh`):
0102
0103 ```bash
0104 #!/bin/bash
0105 input=$(cat)
0106 MODEL=$(echo "$input" | jq -r '.model.display_name')
0107 USED=$(echo "$input" | jq -r '.context_window.used_percentage // 0')
0108 REMAINING=$(echo "$input" | jq -r '.context_window.remaining_percentage // 100')
0109 echo "[$MODEL] ${USED}% used | ${REMAINING}% remaining"
0110 ```
0111
0112 ---