DollhouseMCP

# VERIFIED WORKING: Docker Claude Code + DollhouseMCP Integration ## Executive Summary Successfully solved the authentication issue preventing Claude Code CLI from working in Docker containers. The solution uses the **apiKeyHelper** configuration method instead of direct environment variables. **Status**: ✅ FULLY VERIFIED AND WORKING **Date Verified**: September 22, 2025 **Versions Tested**: Claude Code v1.0.110, DollhouseMCP v1.9.8 ## The Problem Claude Code CLI was returning "Invalid API key · Please run /login" even when: - Valid API key was provided via `ANTHROPIC_API_KEY` environment variable - API key was confirmed working with Anthropic's API directly - All infrastructure (Docker, MCP config) was correctly set up ## The Solution: apiKeyHelper Method Claude Code CLI no longer accepts API keys directly through environment variables. Instead, it requires an **apiKeyHelper script** that provides the API key when requested. ### How It Works 1. **Create a helper script** that outputs the API key 2. **Configure Claude Code** to use this helper script 3. **Claude Code calls the script** when it needs authentication ## Complete Working Implementation ### Step 1: Build the Docker Container ```bash # Navigate to project cd /Users/mick/Developer/Organizations/DollhouseMCP/active/mcp-server # Build container docker build -f docker/test-configs/Dockerfile.claude-testing -t claude-mcp-test-env . ``` ### Step 2: Run with apiKeyHelper Setup ```bash # Set your API key export ANTHROPIC_API_KEY="sk-ant-api03-YOUR-KEY" # Run with inline apiKeyHelper setup docker run --rm -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" --entrypoint bash claude-mcp-test-env -c ' # Setup apiKeyHelper mkdir -p /home/claude/.claude echo "#!/bin/bash" > /home/claude/.claude/anthropic_key_helper.sh echo "echo \${ANTHROPIC_API_KEY}" >> /home/claude/.claude/anthropic_key_helper.sh chmod +x /home/claude/.claude/anthropic_key_helper.sh claude config set --global apiKeyHelper /home/claude/.claude/anthropic_key_helper.sh # Your Claude Code command here echo "Your prompt" | claude --model sonnet --print ' ``` ### Step 3: Using with MCP Tools ```bash docker run --rm -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" --entrypoint bash claude-mcp-test-env -c ' # Setup apiKeyHelper mkdir -p /home/claude/.claude echo "#!/bin/bash" > /home/claude/.claude/anthropic_key_helper.sh echo "echo \${ANTHROPIC_API_KEY}" >> /home/claude/.claude/anthropic_key_helper.sh chmod +x /home/claude/.claude/anthropic_key_helper.sh claude config set --global apiKeyHelper /home/claude/.claude/anthropic_key_helper.sh # Use MCP tools echo "Use mcp__dollhousemcp__list_elements to list personas" | \ claude --model sonnet --print \ --mcp-config /home/claude/.config/claude-code/config.json \ --allowedTools mcp__dollhousemcp__list_elements ' ``` ## Verification Results ### Test 1: Basic Functionality ✅ ```bash Command: echo "Say VERIFICATION_PASSED" | claude --model sonnet --print Result: VERIFICATION_PASSED ``` ### Test 2: MCP Tools Detection ✅ ```bash Command: List all MCP tools Result: 34 DollhouseMCP tools detected ``` ### Test 3: MCP Tool Execution ✅ ```bash Command: Use mcp__dollhousemcp__get_build_info Result: DollhouseMCP server version 1.9.8 running ``` ## Updated Dockerfile for Permanent Solution To make this permanent, update your Dockerfile to include the apiKeyHelper setup: ```dockerfile # Add after Claude Code installation RUN mkdir -p /home/claude/.claude && \ echo '#!/bin/bash' > /home/claude/.claude/anthropic_key_helper.sh && \ echo 'echo ${ANTHROPIC_API_KEY}' >> /home/claude/.claude/anthropic_key_helper.sh && \ chmod +x /home/claude/.claude/anthropic_key_helper.sh && \ chown -R claude:claude /home/claude/.claude # Configure Claude Code to use the helper USER claude RUN claude config set --global apiKeyHelper /home/claude/.claude/anthropic_key_helper.sh ``` ## Helper Script for Easy Testing Create `scripts/claude-docker-with-auth.sh`: ```bash #!/bin/bash if [ -z "$ANTHROPIC_API_KEY" ]; then echo "Error: ANTHROPIC_API_KEY not set" exit 1 fi docker run --rm -it \ -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \ --entrypoint bash \ claude-mcp-test-env -c " # Setup auth mkdir -p /home/claude/.claude echo '#!/bin/bash' > /home/claude/.claude/anthropic_key_helper.sh echo 'echo \${ANTHROPIC_API_KEY}' >> /home/claude/.claude/anthropic_key_helper.sh chmod +x /home/claude/.claude/anthropic_key_helper.sh claude config set --global apiKeyHelper /home/claude/.claude/anthropic_key_helper.sh >/dev/null 2>&1 # Run Claude Code claude --model sonnet --print --mcp-config /home/claude/.config/claude-code/config.json \$@ " -- "$@" ``` ## Why This Changed Based on GitHub issues and documentation: 1. **OAuth-First Design**: Claude Code CLI moved to OAuth-based authentication for Claude.ai subscribers 2. **API Key Deprecation**: Direct environment variable support was removed 3. **apiKeyHelper Bridge**: Provides backward compatibility for API key users 4. **Security Model**: Prevents accidental API key exposure in logs ## Common Issues and Solutions ### Issue: Still Getting "Invalid API key" **Solution**: Ensure the helper script is executable and returns ONLY the API key ### Issue: MCP Tools Not Working **Solution**: Use `--allowedTools` flag to pre-approve tools in non-interactive mode ### Issue: Permission Errors **Solution**: Run as the `claude` user, not root ## Key Flags for Non-Interactive Use - `--print` - Non-TTY/pipe mode (required for Docker) - `--allowedTools` - Pre-approve specific MCP tools - `--mcp-config` - Load MCP configuration - `--model sonnet` - Use Claude 3.5 Sonnet ## Complete Working Example ```bash # One-liner that works echo "List all personas using DollhouseMCP" | \ docker run --rm -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" --entrypoint bash claude-mcp-test-env -c ' mkdir -p /home/claude/.claude && \ echo "#!/bin/bash" > /home/claude/.claude/anthropic_key_helper.sh && \ echo "echo \${ANTHROPIC_API_KEY}" >> /home/claude/.claude/anthropic_key_helper.sh && \ chmod +x /home/claude/.claude/anthropic_key_helper.sh && \ claude config set --global apiKeyHelper /home/claude/.claude/anthropic_key_helper.sh >/dev/null 2>&1 && \ claude --model sonnet --print \ --mcp-config /home/claude/.config/claude-code/config.json \ --allowedTools mcp__dollhousemcp__list_elements ' ``` ## Conclusion The apiKeyHelper method successfully bridges the gap between API key authentication and Claude Code CLI's OAuth-focused design. This solution is: - ✅ **Verified Working**: All tests pass - ✅ **Docker Compatible**: Works in containers - ✅ **MCP Integrated**: Full DollhouseMCP tool access - ✅ **CI/CD Ready**: Non-interactive mode supported - ✅ **Documented**: Complete implementation guide --- *Solution discovered and verified: September 22, 2025* *Author: Alex Sterling with Session Notes Writer*