Using MCP Tools

After you add and connect an MCP server, the tools it provides are automatically registered in the Agent's available toolset. This page explains how tools are discovered, named, and used, and how to manage them in detail.

Automatic Tool Discovery

When an MCP server connects successfully, Elftia automatically performs the following:

1. Fetch tool list — Calls the server's listTools endpoint to retrieve all available tools
2. Register format — Registers the tools in the internal tool system
3. Cache storage — The tool list is cached for 5 minutes to avoid frequent requests

Cache Behavior

Behavior	Description
Cache duration	5 minutes (300 seconds)
Cache scope	Cached separately per server ID
Auto-refresh	Fetches the latest list automatically on the next request after the cache expires
Manual refresh	Click the Discover button in the MCP server list to force a refresh
Reconnect	Disconnecting and reconnecting a server clears its cache

Manual Discovery

On the MCP Servers page, you can run Discover on each server to view its full capability summary:

• Tools — Functions the Agent can call
• Resources — Data resources provided by the server (such as files, database tables, etc.)
• Prompts — Prompt templates predefined by the server

Tool Naming Format

Each MCP tool's identifier in the Agent follows this format:

mcp__<server-name>__<tool-name>

Naming rules:

• Non-alphanumeric characters in the server name and tool name are replaced with an underscore _
• Double underscores __ are used as separators

Examples:

Server name	Original tool name	Identifier in Agent
filesystem	read_file	mcp__filesystem__read_file
brave-search	brave_web_search	mcp__brave_search__brave_web_search
github	create_issue	mcp__github__create_issue

MCP Usage Modes

Elftia provides three MCP usage modes that control tool availability during a conversation:

Mode	Description	Use case
Automatic (default)	Tools from all enabled servers are available automatically	Everyday use; Agent selects tools on its own
Manual	Choose which servers to use before each conversation	Scenarios requiring precise control over the tool scope
Disabled	MCP tools are completely turned off	Simple conversations that do not need external tools

Automatic Mode

The default mode. Tools from all active (isActive) MCP servers are automatically added to the Agent's tool list. The Agent decides on its own whether to call a tool based on the conversation content.

Manual Mode

In manual mode, you can precisely select which MCP servers to use for the current conversation:

1. Switch the MCP mode in the conversation settings to Manual
2. Check the servers you need from the available server list
3. Only the tools from the selected servers are available during the conversation

Disabled Mode

Completely disables MCP functionality. The Agent does not load any MCP tools.

Tool Format Adaptation

Elftia supports multiple LLM providers, each with a different tool-calling format. MCP tools are automatically converted to the format required by the current provider:

Provider	Tool format	Description
OpenAI / DeepSeek / Chinese LLMs	function format	{ type: "function", function: { name, description, parameters } }
Anthropic (Claude)	tool format	{ name, description, input_schema }
Google (Gemini)	functionDeclarations format	{ functionDeclarations: [{ name, description, parameters }] }

This conversion is completely automatic and requires no manual intervention.

How Tools Appear in the Conversation

When the Agent invokes an MCP tool, the conversation UI displays a dedicated tool-call card:

• Calling — Shows the tool name and the arguments passed to it
• Result — Displays the content returned by the tool (text, images, etc.)
• Error — If the call fails, the error details are shown

Tool Return Content Types

MCP tools can return the following types of content:

Content type	Description
text	Text result, displayed directly
image	Image data (Base64-encoded), rendered as an image
audio	Audio data (Base64-encoded), rendered as a player

Call Timeout

The timeout for a single tool call is 2 minutes (120 seconds). If the tool does not return a result within this time, the call is terminated and a timeout error is returned.

Associating MCP Servers with Agents

You can associate specific MCP servers with specific Agents for finer-grained tool allocation:

Association Steps

1. In the MCP server list, click the Manage button on the target server
2. In the dialog that appears, view the list of already-associated Agents
3. Click Add to Agent to expand the list of available Agents
4. Select the Agents you want to associate

Managing Associations

In the management dialog, you can:

Action	Description
View associated Agents	Shows which Agents are currently associated
Enable/Disable	Use the toggle to control tool availability for a specific Agent
Remove association	Click the delete button to remove an Agent association
Search Agents	Search and filter the Agent list when adding

Disabling Specific Tools

If an MCP server provides too many tools, or there are specific tools you don't want the Agent to use, you can selectively disable them:

• The server-level disabledTools list records the names of disabled tools
• Disabled tools do not appear in the Agent's tool list
• Disabling is done via the server update interface

Trust Management

MCP servers have two trust levels:

Level	Description	Behavioral difference
Untrusted (default)	Newly added servers are untrusted by default	Normal use, but may be subject to additional restrictions
Trusted	Servers the user has explicitly marked as trustworthy	Full trust for tool calls

Marking as Trusted

Update the server's isTrusted property in server management to mark it as trusted. Trusted servers have elevated permissions when tool calls are auto-approved.

Enabling and Disabling Servers

Each MCP server has an isActive toggle:

• Enabled — The server participates in tool loading (in automatic mode it connects automatically)
• Disabled — The server is skipped, does not participate in tool loading, and consumes no connection resources

Disabling a server does not delete its configuration; it can be re-enabled at any time.

Troubleshooting

Tool Call Returns an Error

Symptom: An error message is displayed after the Agent invokes a tool.

Solution:

• Check that the API key required by the tool is correctly configured
• Confirm the tool arguments match the expected format
• Verify that the server is still running (for Stdio servers)
• Try reconnecting the server

Tool List Is Empty

Symptom: The server is connected but no tools were discovered.

Solution:

• Use the Discover function to manually fetch the tool list
• Confirm the server version supports the tools/list endpoint
• Check the server's log output for errors

Agent Is Not Using Available Tools

Symptom: The tools are registered but the Agent does not call them during the conversation.

Solution:

• Explicitly mention the tool name or related capability in the prompt
• Check whether the mode is set to disabled
• Confirm the tool's description is accurate so the Agent can judge when to use it
• Reduce the number of available tools to avoid choice paralysis

Next Steps

• Adding MCP Servers — Configure additional MCP servers
• JSON Bulk Import — Quickly import configurations via JSON
• MCP Overview — Review MCP core concepts