Adding MCP Servers

This page explains how to add and configure MCP servers in Elftia. Elftia supports three transport types, and the configuration steps differ slightly for each.

Open the MCP Management Page

1. Click the MCP Servers page in the left navigation bar
2. Click the Add button in the upper right
3. In the form that appears, select Form Input mode

tip

You can also add servers in bulk using JSON Import mode. See JSON Bulk Import.

Adding a Stdio Server

Stdio is the most common transport type, used for MCP servers launched via a local command line (such as npm or pip packages).

Configuration Steps

1. Server name — Enter an easy-to-recognize name (e.g. filesystem)
2. Transport type — Select Stdio
3. Command — Enter the command to start the server (e.g. npx)
4. Arguments — One argument per line:

   -y
   @modelcontextprotocol/server-filesystem
   /path/to/allowed/directory

5. Environment variables (optional) — One per line in KEY=VALUE format:

   API_KEY=your-api-key
   DEBUG=true

6. Click Save

Configuration Field Descriptions

Field	Required	Description
Server name	Yes	Unique identifier; must not duplicate an existing server name
Command	Yes	Executable command, e.g. npx, uvx, node, python
Arguments	No	List of arguments passed to the command, one per line
Environment variables	No	Additional environment variables for the child process; inherits the current system environment

Common Stdio Server Examples

Filesystem server:

Field	Value
Command	npx
Arguments	-y , @modelcontextprotocol/server-filesystem , /Users/yourname/Documents

Brave Search server:

Field	Value
Command	npx
Arguments	-y , @modelcontextprotocol/server-brave-search@latest
Environment variables	BRAVE_API_KEY=your-brave-api-key

Tavily Search server:

Field	Value
Command	npx
Arguments	-y , tavily-mcp@latest
Environment variables	TAVILY_API_KEY=your-tavily-api-key

Adding an SSE Server

SSE (Server-Sent Events) is used for remotely hosted MCP servers that communicate via an HTTP long connection.

Configuration Steps

1. Server name — Enter a name (e.g. web-search)
2. Transport type — Select SSE
3. URL — Enter the server's SSE endpoint address
4. Request headers (optional) — One per line in Key=Value format:

   Authorization=Bearer your-token
   X-API-Key=your-api-key

5. Environment variables (optional) — Same as for Stdio
6. Click Save

Configuration Field Descriptions

Field	Required	Description
Server name	Yes	Unique identifier
URL	Yes	The SSE endpoint URL of the MCP server
Request headers	No	HTTP request headers, used for authentication, etc.
Environment variables	No	Additional environment variables

SSE Server Example

Zhipu Web Search:

Field	Value
URL	https://api.z.ai/api/mcp/web_search_prime/mcp
Request headers	Authorization=Bearer your-zhipu-api-key

Adding an HTTP Server

HTTP transport (Streamable HTTP) is based on the MCP 2025-03-26 spec and is the newer transport option.

Configuration Steps

1. Server name — Enter a name
2. Transport type — Select HTTP
3. URL — Enter the server's HTTP endpoint address
4. Request headers (optional) — Same as for SSE
5. Click Save

Configuration Field Descriptions

Same as SSE, differing only in the transport protocol used.

Field	Required	Description
Server name	Yes	Unique identifier
URL	Yes	The HTTP endpoint URL of the MCP server
Request headers	No	HTTP request headers
Environment variables	No	Additional environment variables

HTTP Server Example

Zhipu Web Reader:

Field	Value
URL	https://api.z.ai/api/mcp/web_reader/mcp
Request headers	Authorization=Bearer your-zhipu-api-key

Dependency Check

When adding a Stdio server, Elftia automatically checks whether the required CLI tools are installed:

Command	What is checked	Auto-install method
npx / npm / node	Node.js runtime	Windows: winget; macOS: Homebrew; other: prompts for manual install
uv / uvx	uv Python package manager	Installed automatically via the official install script

If a missing dependency is detected, Elftia shows a prompt offering automatic installation or a link to the manual download page.

Dependency Check Behavior

• First looks for the command in the system PATH
• If not found, automatically scans common installation directories (~/.local/bin, ~/.cargo/bin, npm global directory, etc.)
• After installation, automatically verifies availability
• For dependencies that cannot be installed automatically, provides a link to the download page

Testing the Connection

After adding a server, it is recommended to test the connection immediately:

1. Find the target server in the MCP server list
2. Click the Test button
3. Wait for the connection and tool discovery to complete
4. On success, the message Connected successfully. Found N tools. is displayed along with a list of tool names

Using Official Presets

Elftia includes preset configurations for some common MCP servers that support one-click installation:

1. Switch to the Official tab on the MCP Servers page
2. Browse the available presets (filter by category: search, vision, web reading, code repository, etc.)
3. Click the Install button
4. If an API key is required, the system will try to auto-associate it from an already-configured LLM provider; if none is found, you must enter it manually

Currently supported official presets:

Preset	Category	Transport	Requires API Key
MiniMax Coding Plan MCP	General	Stdio	Yes
Zhipu Vision MCP	Vision	Stdio	Yes
Zhipu Web Search	Search	HTTP	Yes
Zhipu Web Reader	Web reading	HTTP	Yes
Zhipu Zread	Code repository	HTTP	Yes
Tavily Search	Search	Stdio	Yes
Brave Search	Search	Stdio	Yes

Troubleshooting

Command Not Found

Symptom: When adding a Stdio server, a message says the command does not exist.

Solution:

• Confirm the relevant runtime is installed (Node.js, Python, etc.)
• Try running the command manually in a terminal to verify
• Restart Elftia to refresh the PATH environment variable
• Use the full path instead of the command name (e.g. /usr/local/bin/npx)

Connection Timeout

Symptom: No response for a long time when testing the connection.

Solution:

• Check the network connection (for SSE/HTTP servers)
• Confirm the URL is correct, especially the port and path
• Check whether a firewall or proxy is blocking the connection
• For Stdio servers, confirm the command can start normally

Authentication Error

Symptom: Connection succeeds but tool calls fail with authentication-related errors.

Solution:

• Check that the API key is correctly set in environment variables
• For SSE/HTTP servers, confirm the authentication information in the request headers is correctly formatted
• Note the Bearer token format: Authorization=Bearer your-token

Tools Not Showing

Symptom: Server connected successfully but tools do not appear in the conversation.

Solution:

• Confirm the server is in the enabled state (isActive is true)
• Check whether the MCP mode is set to disabled
• In manual mode, confirm the server has been selected
• Try using the Discover button to manually refresh the tool list
• The tool cache expires every 5 minutes — wait for the cache to refresh or reconnect

Next Steps

• JSON Bulk Import — Quickly import multiple servers via JSON
• Using MCP Tools — Learn how tools are used during a conversation