Configuration Import

MCPProxy can import MCP server configurations from popular AI tools, making it easy to migrate your existing setups or consolidate servers from multiple sources.

Supported Formats

Source	Format	File Location
Claude Desktop	JSON	macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
Windows: `%APPDATA%\Claude\claude_desktop_config.json`
Linux: `~/.config/Claude/claude_desktop_config.json`
Claude Code	JSON	`~/.claude.json` (all platforms)
Cursor IDE	JSON	`~/.cursor/mcp.json` (all platforms)
Codex CLI	TOML	`~/.codex/config.toml` (all platforms)
Gemini CLI	JSON	`~/.gemini/settings.json` (all platforms)

Web UI Import

Quick Import Panel

The Web UI provides a Quick Import panel that automatically detects installed AI tools on your system:

Open MCPProxy Web UI
Click Add Server → Import tab
The Quick Import - Found Configs panel shows detected configurations
Click Import next to any found config to preview servers
Select which servers to import and click Import N Servers

The panel shows:

Found (green badge): Config file exists, click Import to load
Not found (gray): Config file not present on this system

Manual File Upload

You can also upload configuration files manually:

Click Add Server → Import → Upload File
Click Choose File and select your config file
Format is auto-detected, or select manually from dropdown
Preview shows detected servers with details
Select servers and click Import

Paste Content

For quick imports without file access:

Click Add Server → Import → Paste Content
Paste JSON or TOML configuration content
Content is validated with line numbers shown for errors
Preview and import selected servers

CLI Import

Import from File Path

bash

# Import from Claude Desktop config
mcpproxy upstream import ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Import from Claude Code config
mcpproxy upstream import ~/.claude.json

# Import with format hint (if auto-detect fails)
mcpproxy upstream import --format claude-desktop config.json

# Preview without importing
mcpproxy upstream import --dry-run config.json

# Import without quarantine (trusted configs)
mcpproxy upstream import --no-quarantine ~/Library/Application\ Support/Claude/claude_desktop_config.json

Import Specific Servers

bash

# Import only a specific server by name
mcpproxy upstream import --server github-server config.json

REST API

Get Canonical Config Paths

Returns well-known configuration paths for the current OS with existence status:

bash

curl -H "X-API-Key: your-key" \
  http://127.0.0.1:8080/api/v1/servers/import/paths

Response:

json

{
  "success": true,
  "data": {
    "os": "darwin",
    "paths": [
      {
        "name": "Claude Desktop",
        "format": "claude-desktop",
        "path": "/Users/user/Library/Application Support/Claude/claude_desktop_config.json",
        "exists": true,
        "description": "Claude Desktop app configuration"
      },
      {
        "name": "Claude Code (User)",
        "format": "claude-code",
        "path": "/Users/user/.claude.json",
        "exists": true,
        "description": "Claude Code user-level MCP servers"
      }
    ]
  }
}

Import from Path

Import servers by reading a file from the server's filesystem:

bash

# Preview import
curl -X POST -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"path": "/Users/user/.claude.json", "format": "claude-code"}' \
  "http://127.0.0.1:8080/api/v1/servers/import/path?preview=true"

# Actual import
curl -X POST -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"path": "/Users/user/.claude.json"}' \
  http://127.0.0.1:8080/api/v1/servers/import/path

Import from Content

Import by posting configuration content directly:

bash

curl -X POST -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "{\"mcpServers\": {\"my-server\": {\"command\": \"npx\", \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem\"]}}}",
    "format": "claude-desktop"
  }' \
  http://127.0.0.1:8080/api/v1/servers/import/json

Upload File

Import by uploading a multipart form file:

bash

curl -X POST -H "X-API-Key: your-key" \
  -F "file=@/path/to/config.json" \
  "http://127.0.0.1:8080/api/v1/servers/import?preview=true"

Import Response

All import endpoints return a consistent response format:

json

{
  "success": true,
  "data": {
    "format": "claude-desktop",
    "format_name": "Claude Desktop",
    "summary": {
      "total": 5,
      "imported": 3,
      "skipped": 1,
      "failed": 1
    },
    "imported": [
      {
        "name": "filesystem",
        "protocol": "stdio",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem"],
        "source_format": "claude-desktop",
        "original_name": "filesystem"
      }
    ],
    "skipped": [
      {
        "name": "existing-server",
        "reason": "Server with this name already exists"
      }
    ],
    "failed": [
      {
        "name": "invalid-server",
        "reason": "Missing required field: command",
        "original_config": {}
      }
    ],
    "warnings": ["Server 'github' has no tools configured"]
  }
}

Format Detection

MCPProxy auto-detects the configuration format by analyzing:

File extension: .toml → Codex CLI format
JSON structure:
- mcpServers object → Claude Desktop
- Top-level mcpServers with env at server level → Claude Code
- Root-level server definitions → Cursor IDE
- mcpServers in tools section → Gemini CLI

You can override auto-detection with the format parameter:

claude-desktop
claude-code
cursor
codex
gemini

Handling Duplicates

When importing, MCPProxy checks for existing servers by name:

Existing servers are skipped by default
Skipped servers appear in the skipped array with reason
Use the preview mode to see what will be imported before committing

Security Considerations

Imported servers are quarantined by default for security review
Review imported server configurations before enabling them
Environment variables and secrets are imported as-is; consider using secret references
File paths are validated to prevent directory traversal attacks