tools-only MCP Server Integration
Overview
MCP (Model Context Protocol) servers allow you to extend Claude's capabilities with custom tools and functions. While the CCProxy API doesn't directly support function calling, you can leverage MCP servers through Claude Code's built-in MCP support.
Setup Requirements
MCP servers must be registered using the Claude CLI in the environment where Claude Code is running:
# Add an MCP server
claude mcp add <server-name> <server-config>
# List registered MCP servers
claude mcp list
# Remove an MCP server
claude mcp remove <server-name>
Configuration Locations:
- Current directory:
.claude/mcp.json - Global configuration:
~/.claude/mcp.json - Git repository root:
<repo-root>/.claude/mcp.json
Local Machine Deployment
When running the proxy on your local machine, you can use any MCP server deployment method:
NPX/Node.js Servers
claude mcp add filesystem '{"command": "npx", "args": ["@anthropic/mcp-server-filesystem", "/path/to/directory"]}'
UVX/Python Servers
claude mcp add python-server '{"command": "uvx", "args": ["mcp-server-package", "--config", "config.json"]}'
Docker-based Servers
claude mcp add docker-server '{"command": "docker", "args": ["run", "--rm", "-i", "your-mcp-server-image"]}'
Native Binaries
claude mcp add native-server '{"command": "/path/to/mcp-server-binary", "args": ["--config", "config.json"]}'
Docker Container Deployment
When Claude Code runs inside a Docker container, MCP server options are more limited.
Supported Methods
NPX/Node.js: Install Node.js in the container
RUN apt-get update && apt-get install -y nodejs npm
UVX/Python: Install Python and uv in the container
RUN apt-get update && apt-get install -y python3 python3-pip
RUN pip install uv
Native binaries: Include binaries in the container image
Docker Socket Method (Advanced)
# Mount Docker socket for container access
docker run -v /var/run/docker.sock:/var/run/docker.sock ccproxy
Security Warning: Mounting /var/run/docker.sock breaks container isolation and allows Docker escape. This creates significant security risks and should only be used in trusted environments with full understanding of the implications.
Common MCP Server Examples
Filesystem Access
claude mcp add filesystem '{"command": "npx", "args": ["@anthropic/mcp-server-filesystem", "/workspace"]}'
Database Integration
claude mcp add database '{"command": "uvx", "args": ["mcp-server-sqlite", "--db-path", "/data/app.db"]}'
Web Scraping
claude mcp add web-scraper '{"command": "npx", "args": ["@anthropic/mcp-server-puppeteer"]}'
Custom API Client
claude mcp add api-client '{"command": "./mcp-servers/api-client", "args": ["--config", "api-config.json"]}'
Usage Flow
- Register MCP servers using
claude mcp addin the environment where Claude Code runs - Start the CCProxy API
- Make API requests - Claude automatically uses registered MCP servers for relevant requests
- Function calls are handled internally by Claude Code, not exposed through the API
Best Practices
- Test MCP servers independently before integrating with the proxy
- Use specific server configurations rather than broad access permissions
- Monitor resource usage of MCP servers in production
- Keep MCP server configurations in version control when possible
- Document custom MCP servers for team members
Troubleshooting
Common Issues
MCP server not responding:
- Check if the server command is accessible in the environment
- Verify configuration JSON syntax
- Review Claude logs for connection errors
Docker container can't access local services:
- Use host networking or container-to-container communication
- Avoid mounting Docker socket unless absolutely necessary
Permission errors:
- Ensure Claude has proper permissions to execute MCP server commands
- Check file system permissions for server binaries and configs
Debugging
# Test MCP server connection
claude mcp test <server-name>
# View detailed logs
claude --log-level debug
# List active MCP connections
claude mcp status
This integration approach provides powerful extensibility while maintaining the simplicity of the proxy API interface.