642 lines
13 KiB
Markdown
642 lines
13 KiB
Markdown
# Configuration Patterns - Complete Reference
|
|
|
|
**When to use this reference:** Adding new MCP servers to MCPProxy or fixing configuration issues.
|
|
|
|
This reference provides complete configuration structures for all server types with detailed explanations.
|
|
|
|
## Configuration File Location
|
|
|
|
`~/.mcpproxy/mcp_config.json`
|
|
|
|
**Important:** After editing, trigger reload:
|
|
```bash
|
|
touch ~/.mcpproxy/mcp_config.json
|
|
# OR restart mcpproxy
|
|
pkill mcpproxy && open /Applications/mcpproxy.app
|
|
```
|
|
|
|
## Complete Configuration Patterns
|
|
|
|
### Pattern 1: uvx/npx Servers (Package Managers)
|
|
|
|
**Key rule:** Package name MUST be first argument.
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"server-name": {
|
|
"protocol": "stdio",
|
|
"command": "uvx", // or "npx"
|
|
"args": [
|
|
"package-name", // CRITICAL: Package name FIRST
|
|
"--arg1", // Then package arguments
|
|
"value1",
|
|
"--arg2",
|
|
"value2"
|
|
],
|
|
"env": {
|
|
// Optional environment variables
|
|
"API_KEY": "secret",
|
|
"DEBUG": "true"
|
|
},
|
|
"working_dir": "/path/to/dir", // Optional working directory
|
|
"enabled": true,
|
|
"quarantined": false
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Real examples:**
|
|
|
|
#### Time Server with Timezone
|
|
```json
|
|
{
|
|
"time": {
|
|
"protocol": "stdio",
|
|
"command": "uvx",
|
|
"args": [
|
|
"mcp-server-time",
|
|
"--local-timezone",
|
|
"America/New_York"
|
|
],
|
|
"enabled": true,
|
|
"quarantined": false
|
|
}
|
|
}
|
|
```
|
|
|
|
#### SQLite Server with Database Path
|
|
```json
|
|
{
|
|
"sqlite": {
|
|
"protocol": "stdio",
|
|
"command": "uvx",
|
|
"args": [
|
|
"mcp-server-sqlite",
|
|
"--db-path",
|
|
"/Users/username/data/mydb.sqlite"
|
|
],
|
|
"enabled": true,
|
|
"quarantined": false
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Filesystem Server with Paths
|
|
```json
|
|
{
|
|
"filesystem": {
|
|
"protocol": "stdio",
|
|
"command": "npx",
|
|
"args": [
|
|
"@modelcontextprotocol/server-filesystem",
|
|
"/Users/username/workspace",
|
|
"/Users/username/Documents"
|
|
],
|
|
"enabled": true,
|
|
"quarantined": false
|
|
}
|
|
}
|
|
```
|
|
|
|
**Common mistakes:**
|
|
```json
|
|
// ❌ WRONG - Arguments before package name
|
|
{
|
|
"command": "uvx",
|
|
"args": ["--local-timezone", "America/New_York"]
|
|
// Error: "unexpected argument '--local-timezone' found"
|
|
}
|
|
|
|
// ✅ CORRECT - Package name first
|
|
{
|
|
"command": "uvx",
|
|
"args": ["mcp-server-time", "--local-timezone", "America/New_York"]
|
|
}
|
|
```
|
|
|
|
### Pattern 2: Docker-Based Servers
|
|
|
|
**Key rules:**
|
|
1. Use `-i` (NOT `-it`) for stdin pipe
|
|
2. ALWAYS disable isolation to prevent Docker-in-Docker
|
|
|
|
```json
|
|
{
|
|
"docker-server": {
|
|
"protocol": "stdio",
|
|
"command": "docker",
|
|
"args": [
|
|
"run",
|
|
"-i", // CRITICAL: -i only, not -it
|
|
"--rm", // Clean up container after exit
|
|
"-e", "VAR_NAME", // Pass environment variables
|
|
"image:tag", // Docker image
|
|
"subcommand" // Optional: server entrypoint
|
|
],
|
|
"env": {
|
|
"VAR_NAME": "value" // Values for -e flags
|
|
},
|
|
"isolation": {
|
|
"enabled": false // CRITICAL: Disable to prevent Docker-in-Docker
|
|
},
|
|
"enabled": true,
|
|
"quarantined": false
|
|
}
|
|
}
|
|
```
|
|
|
|
**Real examples:**
|
|
|
|
#### Basic Docker MCP Server
|
|
```json
|
|
{
|
|
"docker-mcp": {
|
|
"protocol": "stdio",
|
|
"command": "docker",
|
|
"args": [
|
|
"run",
|
|
"-i",
|
|
"--rm",
|
|
"ghcr.io/example/mcp-server:latest"
|
|
],
|
|
"isolation": {
|
|
"enabled": false
|
|
},
|
|
"enabled": true,
|
|
"quarantined": false
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Docker Server with Environment Variables
|
|
```json
|
|
{
|
|
"api-server": {
|
|
"protocol": "stdio",
|
|
"command": "docker",
|
|
"args": [
|
|
"run",
|
|
"-i",
|
|
"--rm",
|
|
"-e", "API_KEY",
|
|
"-e", "API_URL",
|
|
"mycompany/api-mcp:v1.0"
|
|
],
|
|
"env": {
|
|
"API_KEY": "sk-xxxx",
|
|
"API_URL": "https://api.example.com"
|
|
},
|
|
"isolation": {
|
|
"enabled": false
|
|
},
|
|
"enabled": true,
|
|
"quarantined": false
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Docker Server with Volume Mounts
|
|
```json
|
|
{
|
|
"file-processor": {
|
|
"protocol": "stdio",
|
|
"command": "docker",
|
|
"args": [
|
|
"run",
|
|
"-i",
|
|
"--rm",
|
|
"-v", "/Users/username/data:/data:ro",
|
|
"mycompany/file-mcp:latest",
|
|
"--data-dir", "/data"
|
|
],
|
|
"isolation": {
|
|
"enabled": false
|
|
},
|
|
"enabled": true,
|
|
"quarantined": false
|
|
}
|
|
}
|
|
```
|
|
|
|
**Common mistakes:**
|
|
```json
|
|
// ❌ WRONG - Using -it flags
|
|
{
|
|
"command": "docker",
|
|
"args": ["run", "-it", "--rm", "image:tag"]
|
|
// Error: "the input device is not a TTY"
|
|
}
|
|
|
|
// ❌ WRONG - Isolation enabled
|
|
{
|
|
"command": "docker",
|
|
"args": ["run", "-i", "--rm", "image:tag"],
|
|
"isolation": {"enabled": true}
|
|
// Error: Docker-in-Docker, "not a TTY"
|
|
}
|
|
|
|
// ✅ CORRECT - Use -i only, disable isolation
|
|
{
|
|
"command": "docker",
|
|
"args": ["run", "-i", "--rm", "image:tag"],
|
|
"isolation": {"enabled": false}
|
|
}
|
|
```
|
|
|
|
### Pattern 3: HTTP/SSE Servers
|
|
|
|
For servers accessed via HTTP or Server-Sent Events.
|
|
|
|
```json
|
|
{
|
|
"http-server": {
|
|
"protocol": "http", // or "sse"
|
|
"url": "https://api.example.com/mcp",
|
|
"headers": {
|
|
// Optional authentication headers
|
|
"Authorization": "Bearer token",
|
|
"X-API-Key": "secret"
|
|
},
|
|
"enabled": true,
|
|
"quarantined": false
|
|
}
|
|
}
|
|
```
|
|
|
|
**Real examples:**
|
|
|
|
#### HTTP Server with Bearer Token
|
|
```json
|
|
{
|
|
"remote-api": {
|
|
"protocol": "http",
|
|
"url": "https://mcp.example.com/v1",
|
|
"headers": {
|
|
"Authorization": "Bearer sk-xxxxxxxxxxxx"
|
|
},
|
|
"enabled": true,
|
|
"quarantined": false
|
|
}
|
|
}
|
|
```
|
|
|
|
#### SSE Server with API Key
|
|
```json
|
|
{
|
|
"streaming-api": {
|
|
"protocol": "sse",
|
|
"url": "https://stream.example.com/mcp",
|
|
"headers": {
|
|
"X-API-Key": "api-key-here"
|
|
},
|
|
"enabled": true,
|
|
"quarantined": false
|
|
}
|
|
}
|
|
```
|
|
|
|
#### HTTP Server Without Authentication
|
|
```json
|
|
{
|
|
"public-api": {
|
|
"protocol": "http",
|
|
"url": "http://localhost:3000/mcp",
|
|
"enabled": true,
|
|
"quarantined": false
|
|
}
|
|
}
|
|
```
|
|
|
|
### Pattern 4: Local Command Servers
|
|
|
|
For locally installed commands (not uvx/npx).
|
|
|
|
```json
|
|
{
|
|
"local-server": {
|
|
"protocol": "stdio",
|
|
"command": "/usr/local/bin/mcp-server", // Full path or command in PATH
|
|
"args": [
|
|
"--config", "/path/to/config.json",
|
|
"--verbose"
|
|
],
|
|
"env": {
|
|
"HOME": "/Users/username",
|
|
"PYTHONPATH": "/path/to/modules"
|
|
},
|
|
"working_dir": "/Users/username/workspace",
|
|
"enabled": true,
|
|
"quarantined": false
|
|
}
|
|
}
|
|
```
|
|
|
|
**Real examples:**
|
|
|
|
#### Python Script as Server
|
|
```json
|
|
{
|
|
"custom-python": {
|
|
"protocol": "stdio",
|
|
"command": "python",
|
|
"args": [
|
|
"/Users/username/mcp-servers/my_server.py",
|
|
"--config", "production"
|
|
],
|
|
"env": {
|
|
"PYTHONUNBUFFERED": "1"
|
|
},
|
|
"working_dir": "/Users/username/mcp-servers",
|
|
"enabled": true,
|
|
"quarantined": false
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Node.js Script as Server
|
|
```json
|
|
{
|
|
"custom-node": {
|
|
"protocol": "stdio",
|
|
"command": "node",
|
|
"args": [
|
|
"/Users/username/mcp-servers/server.js"
|
|
],
|
|
"env": {
|
|
"NODE_ENV": "production"
|
|
},
|
|
"working_dir": "/Users/username/mcp-servers",
|
|
"enabled": true,
|
|
"quarantined": false
|
|
}
|
|
}
|
|
```
|
|
|
|
## Complete Configuration File Structure
|
|
|
|
```json
|
|
{
|
|
"api_key": "mcpproxy-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
|
|
"listen": "127.0.0.1:8080",
|
|
"docker_isolation": {
|
|
"enabled": true,
|
|
"memory_limit": "512m",
|
|
"cpu_limit": "1.0",
|
|
"timeout": "30s",
|
|
"network_mode": "bridge",
|
|
"default_images": {
|
|
"uvx": "python:3.11",
|
|
"npx": "node:20",
|
|
"python": "python:3.11",
|
|
"node": "node:20"
|
|
}
|
|
},
|
|
"mcpServers": {
|
|
"server1": {
|
|
"protocol": "stdio",
|
|
"command": "uvx",
|
|
"args": ["package-name"],
|
|
"enabled": true,
|
|
"quarantined": false
|
|
},
|
|
"server2": {
|
|
"protocol": "http",
|
|
"url": "https://api.example.com",
|
|
"enabled": true,
|
|
"quarantined": false
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Common Configuration Mistakes
|
|
|
|
### 1. Missing Package Name (uvx/npx)
|
|
```json
|
|
// ❌ WRONG
|
|
{"command": "uvx", "args": ["--arg", "value"]}
|
|
|
|
// ✅ CORRECT
|
|
{"command": "uvx", "args": ["package-name", "--arg", "value"]}
|
|
```
|
|
|
|
### 2. Wrong Docker Flags
|
|
```json
|
|
// ❌ WRONG - Using -it
|
|
{"command": "docker", "args": ["run", "-it", "--rm", "image"]}
|
|
|
|
// ✅ CORRECT - Using -i only
|
|
{"command": "docker", "args": ["run", "-i", "--rm", "image"]}
|
|
```
|
|
|
|
### 3. Docker Isolation Not Disabled
|
|
```json
|
|
// ❌ WRONG - Isolation enabled for Docker
|
|
{
|
|
"command": "docker",
|
|
"args": ["run", "-i", "--rm", "image"],
|
|
"isolation": {"enabled": true} // Docker-in-Docker!
|
|
}
|
|
|
|
// ✅ CORRECT - Isolation disabled
|
|
{
|
|
"command": "docker",
|
|
"args": ["run", "-i", "--rm", "image"],
|
|
"isolation": {"enabled": false}
|
|
}
|
|
```
|
|
|
|
### 4. Wrong Protocol for Server Type
|
|
```json
|
|
// ❌ WRONG - Using stdio for URL
|
|
{"protocol": "stdio", "url": "https://api.example.com"}
|
|
|
|
// ❌ WRONG - Using http for command
|
|
{"protocol": "http", "command": "uvx", "args": ["package"]}
|
|
|
|
// ✅ CORRECT - Match protocol to type
|
|
{"protocol": "http", "url": "https://api.example.com"}
|
|
{"protocol": "stdio", "command": "uvx", "args": ["package"]}
|
|
```
|
|
|
|
### 5. Server Still Quarantined
|
|
```json
|
|
// ❌ WRONG - Quarantine prevents execution
|
|
{
|
|
"command": "uvx",
|
|
"args": ["package"],
|
|
"quarantined": true // Tools return security analysis!
|
|
}
|
|
|
|
// ✅ CORRECT - Set to false to use tools
|
|
{
|
|
"command": "uvx",
|
|
"args": ["package"],
|
|
"quarantined": false
|
|
}
|
|
```
|
|
|
|
### 6. Invalid JSON
|
|
```json
|
|
// ❌ WRONG - Trailing comma
|
|
{
|
|
"command": "uvx",
|
|
"args": ["package"],
|
|
"enabled": true, // Trailing comma breaks JSON
|
|
}
|
|
|
|
// ✅ CORRECT - No trailing comma
|
|
{
|
|
"command": "uvx",
|
|
"args": ["package"],
|
|
"enabled": true
|
|
}
|
|
```
|
|
|
|
## Environment Variables
|
|
|
|
### Built-in Environment Variables
|
|
|
|
MCPProxy automatically provides:
|
|
- `HOME` - User's home directory
|
|
- `PATH` - System PATH
|
|
|
|
### Custom Environment Variables
|
|
|
|
Add via `env` field:
|
|
```json
|
|
{
|
|
"env": {
|
|
"API_KEY": "secret",
|
|
"DEBUG": "true",
|
|
"CUSTOM_VAR": "value"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Environment Variable Priority
|
|
|
|
For Docker servers:
|
|
1. Variables in Docker args (`-e VAR=value`)
|
|
2. Variables in `env` field passed via `-e VAR` (value from env)
|
|
3. Host environment (if not overridden)
|
|
|
|
**Example:**
|
|
```json
|
|
{
|
|
"command": "docker",
|
|
"args": [
|
|
"run", "-i", "--rm",
|
|
"-e", "API_KEY", // Value from env field
|
|
"-e", "DEBUG=true", // Value in args
|
|
"image:tag"
|
|
],
|
|
"env": {
|
|
"API_KEY": "secret" // Used by -e API_KEY above
|
|
}
|
|
}
|
|
```
|
|
|
|
## Quarantine Settings
|
|
|
|
New servers are automatically quarantined for security. To use them:
|
|
|
|
```json
|
|
{
|
|
"quarantined": false // Set to false to enable tool execution
|
|
}
|
|
```
|
|
|
|
**What quarantine does:**
|
|
- `quarantined: true` - Tools return security analysis instead of executing
|
|
- `quarantined: false` - Tools execute normally
|
|
|
|
**Best practice:** Review new servers before setting `quarantined: false`.
|
|
|
|
## Docker Isolation Configuration
|
|
|
|
See `references/docker-isolation-guide.md` for detailed Docker isolation configuration.
|
|
|
|
**Quick reference:**
|
|
|
|
```json
|
|
{
|
|
// Global settings
|
|
"docker_isolation": {
|
|
"enabled": true, // Master switch
|
|
"memory_limit": "512m", // Default memory per container
|
|
"cpu_limit": "1.0", // Default CPU per container
|
|
"network_mode": "bridge" // Default network mode
|
|
},
|
|
|
|
// Per-server override
|
|
"mcpServers": {
|
|
"my-server": {
|
|
"isolation": {
|
|
"enabled": false, // Disable isolation
|
|
// OR customize:
|
|
"enabled": true,
|
|
"image": "python:3.12",
|
|
"memory_limit": "1g",
|
|
"cpu_limit": "2.0",
|
|
"network_mode": "host"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Verification After Configuration
|
|
|
|
After adding or modifying server configuration:
|
|
|
|
```bash
|
|
# 1. Trigger reload
|
|
touch ~/.mcpproxy/mcp_config.json
|
|
|
|
# 2. Wait for connection (30 seconds)
|
|
sleep 30
|
|
|
|
# 3. Check server status
|
|
curl -s "http://127.0.0.1:8080/api/v1/servers?apikey=YOUR_KEY" | \
|
|
python3 -m json.tool | grep -A 10 '"name": "SERVER_NAME"'
|
|
|
|
# 4. Verify connection
|
|
# Look for:
|
|
# "connected": true
|
|
# "status": "ready"
|
|
# "tool_count": > 0
|
|
|
|
# 5. If not connected, check logs
|
|
tail -50 ~/Library/Logs/mcpproxy/server-SERVER_NAME.log
|
|
```
|
|
|
|
## Configuration Checklist
|
|
|
|
When adding a new server, verify:
|
|
|
|
- [ ] JSON is valid (no trailing commas, quotes matched)
|
|
- [ ] Protocol matches server type (stdio/http/sse)
|
|
- [ ] For uvx/npx: Package name is first argument
|
|
- [ ] For Docker: Using `-i` not `-it`
|
|
- [ ] For Docker: Isolation disabled (`"enabled": false`)
|
|
- [ ] `enabled` is set to `true`
|
|
- [ ] `quarantined` is set to `false` (after review)
|
|
- [ ] Environment variables defined if needed
|
|
- [ ] Config file reloaded (touch or restart)
|
|
- [ ] Server status shows `connected: true` (wait 30s)
|
|
|
|
If server won't connect, see `references/connection-failures.md` for debugging.
|
|
|
|
## Summary
|
|
|
|
Configuration patterns vary by server type. The most common mistakes are:
|
|
1. Missing package name for uvx/npx
|
|
2. Using `-it` instead of `-i` for Docker
|
|
3. Leaving isolation enabled for Docker-based servers
|
|
4. Leaving servers quarantined
|
|
|
|
Follow the pattern for your server type, verify with the checklist, and check logs if it doesn't connect.
|