JSON Bulk Import

In addition to adding servers one at a time via the form, Elftia also supports importing multiple MCP servers at once using JSON configuration. This is especially convenient in the following scenarios:

• Migrating MCP configurations from another tool (such as Claude Desktop or Cursor)
• Sharing a unified server configuration within a team
• Quickly restoring your MCP environment on a new device
• Configuring multiple related servers in one step

Opening JSON Import

1. Open the MCP Servers page
2. Click the Add button
3. In the form that appears, switch to JSON Import mode

JSON Format

Recommended format: mcpServers bulk configuration

This is the recommended JSON format, compatible with the configuration format used by Claude Desktop and similar tools. It supports adding multiple servers at once:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Documents"]
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search@latest"],
      "env": {
        "BRAVE_API_KEY": "your-brave-api-key"
      }
    },
    "web-reader": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

Single-server format

If you only need to add one server, you can use the simplified format:

{
  "name": "my-server",
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "@example/mcp-server"]
}

JSON Field Descriptions

mcpServers format

In the mcpServers object, each key is the server name and its value is the configuration object:

Field	Type	Required	Description
command	string	Required for Stdio	Startup command
args	string[]	No	Command arguments
env	object	No	Environment variable key-value pairs
url	string	Required for SSE/HTTP	Server endpoint URL
headers	object	No	HTTP request headers
type	string	No	Transport type: stdio, sse, or http

:::info Automatic type inference If the type field is not specified, the system infers it automatically:

• Has command → stdio
• Has url → sse :::

Single-server format

Field	Type	Required	Description
name	string	Yes	Server name
type	string	No	Transport type; inferred automatically
command	string	Required for Stdio	Startup command
args	string[]	No	Command arguments
env	object	No	Environment variables
url	string	Required for SSE/HTTP	Server endpoint URL
headers	object	No	HTTP request headers

Complete Examples

Example 1: Filesystem + Search

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/projects"]
    },
    "tavily-search": {
      "command": "npx",
      "args": ["-y", "tavily-mcp@latest"],
      "env": {
        "TAVILY_API_KEY": "tvly-xxxxxxxxxxxxx"
      }
    }
  }
}

Example 2: GitHub + Database

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxxx"
      }
    },
    "sqlite": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sqlite", "/path/to/database.db"]
    }
  }
}

Example 3: Mixed Local and Remote Servers

{
  "mcpServers": {
    "local-files": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Documents"]
    },
    "web-search": {
      "url": "https://api.z.ai/api/mcp/web_search_prime/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key"
      }
    },
    "web-reader": {
      "url": "https://api.z.ai/api/mcp/web_reader/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key"
      }
    }
  }
}

Example 4: Python Tools (using uvx)

{
  "mcpServers": {
    "minimax-tools": {
      "command": "uvx",
      "args": ["minimax-coding-plan-mcp", "-y"],
      "env": {
        "MINIMAX_API_KEY": "your-minimax-key",
        "MINIMAX_API_HOST": "https://api.minimaxi.com"
      }
    }
  }
}

Import Flow

1. Paste the JSON content into the input field
2. The system validates the JSON format in real time; any errors are shown below the input
3. Once validation passes, click Save
4. For Stdio servers, the system automatically checks for required dependencies (such as npx or uvx)
5. If a dependency is missing, an installation prompt appears
6. After all servers are added, the server list is refreshed automatically

Validation Rules

• JSON must be valid JSON
• mcpServers format: each server configuration must include at least one of command, url, or type
• Single-server format: stdio type requires command; http/sse types require url
• Server names must not duplicate existing server names

Sharing Configurations Across Devices

Exporting a Configuration

At present, Elftia's MCP configuration is stored locally in the mcp-config file. You can share it as follows:

1. Edit a server in the MCP server list page to view its full configuration
2. Manually assemble the configuration into JSON format and save it as a file to share

Migrating from Claude Desktop

If you previously configured MCP servers in Claude Desktop, you can copy the mcpServers section directly from its configuration file:

1. Open the Claude Desktop configuration file (typically at ~/.claude/config.json)
2. Find the mcpServers section
3. Format it as the JSON described above
4. Import it in Elftia using JSON Import

:::caution Important Notes

• Make sure API keys and other sensitive values in environment variables are correct before importing
• When exporting configurations, be careful not to expose API keys or other sensitive information
• File paths must be adjusted to match the actual paths on the target device :::

Troubleshooting

JSON Format Error

Symptom: After entering JSON, a red error message appears below.

Solution:

• Check the JSON syntax (brackets, quotes, and commas must be balanced and correctly placed)
• Use a JSON formatting tool to validate the format
• Watch for escape characters (e.g. backslashes in Windows paths must be written as \\)

Some Servers Failed to Add

Symptom: After a bulk import, some servers do not appear in the list.

Solution:

• Check for duplicate server names (names must be unique)
• Check the console for any error messages
• Try adding the failed servers individually using the form

Next Steps

• Using MCP Tools — Learn how tools work in a conversation after being added
• MCP Overview — Review the core MCP concepts