MCP Server Integration

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

1. Register MCP servers using claude mcp add in the environment where Claude Code runs
2. Start the CCProxy API
3. Make API requests - Claude automatically uses registered MCP servers for relevant requests
4. 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.