Skip to main content

MCP Tool Invocation System

GeniSpace agents support a powerful MCP (Model Context Protocol) tool invocation system that extends agent capabilities through built-in tools and external MCP servers. This guide covers the configuration, usage, and management of MCP tools in detail.

MCP Tools Overview​

What Are MCP Tools​

MCP (Model Context Protocol) tools are a standardized interface protocol that allows agents to invoke functions and services. GeniSpace implements a complete MCP tool ecosystem, including:

  • Built-in Tools: Rendering and utility tools that ship with the agent
  • Platform Tools: Operators, tasks, and data sources provided by the platform
  • External Tools: Third-party tools provided through MCP servers
note

Tools only execute when the thinking chain is enabled for the agent.

Tool Categories​

Built-in Tools​

  • Source: Rendering and utility tools that ship with the agent
  • Types: html_render, chart_render, table_render, iframe_embed, url_redirect, editable_document, web_browser, and memory_tools
  • Purpose: Render rich output (HTML, charts, tables, embedded frames, editable documents) and provide utility helpers such as browsing and memory storage
  • Permission Control: Enabled or disabled via the Built-in Tools toggle
note

Built-in tools are rendering/utility tools only. Database queries, email sending, file processing, and similar capabilities are provided by platform operators (see below), not by built-in tools.

Platform Operator Tools​

  • Source: Platform operator system and user-defined custom operators
  • Examples: Database queries, sending email, file processing, and other integrations exposed as operators
  • Naming Convention: operator_identifier_method_identifier
  • Permission Control: Supports selecting all operators or specifying individual ones
  • Features:
    • Displays operator details (name, identifier, description)
    • Shows the list of methods supported by the operator
    • Distinguishes between custom and system operators

Platform Task Tools​

  • Source: Platform task system
  • Invocation Method: Agents can create and execute tasks
  • Task Types: SCHEDULED, EVENT, MANUAL
  • Permission Control: Supports selecting all tasks or specifying individual ones
  • Features:
    • Displays task name, type, and description
    • Agents can use tasks as callable tools
    • Supports task orchestration and execution

Platform Data Source Tools​

  • Source: Platform data source system
  • Invocation Method: Agents can directly query and manipulate data sources
  • Operation Types: READ, CREATE, UPDATE, DELETE
  • Permission Control: Supports selecting all data sources or specifying individual ones
  • Features:
    • Displays data source name, operation type, and description
    • Shows associated database information
    • Agents can execute SQL queries and data operations

External Tools (MCP Server Tools)​

  • Source: External MCP servers
  • Invocation Method: Direct calls to external MCP services
  • Naming Convention: Defined by the server
  • Extensibility: Supports any number of external servers

MCP Tool Configuration​

Basic Configuration​

Configure in the Tools (MCP) tab of the agent configuration page. This tab is only available when the thinking chain is enabled.

There are two independent toggles — there is no single master switch:

1. Built-in Tools​

☑️ Enable Built-in Tools
  • Controls the rendering and utility tools that ship with the agent (html_render, chart_render, table_render, iframe_embed, url_redirect, editable_document, web_browser, memory_tools)
  • Enabled by default

2. Platform Tools​

☑️ Enable Platform Tools
  • Controls access to platform operators, tasks, and data sources (including user-defined and system operators)
  • When enabled, configure the selection strategies below

3. Operator Selection Strategy​

○ Do Not Use Tools - Disable all operator access
○ All Operators - Use all operators the user has permission for
○ Specified Operators - Use only selected specific operators

Specified Operator Selection:

  • Precisely control which operators the agent can use
  • Supports multiple selections for specialized scenarios
  • Displays operator name, identifier, description, and method list
  • Distinguishes between custom and system operators
  • Helps improve security and specialization

4. Task Selection Strategy​

○ Do Not Use Tasks - Disable all task access
○ All Tasks - Agent can create and execute any task
○ Specified Tasks - Limited to selected tasks only

Specified Task Selection:

  • Controls which tasks the agent can create and execute
  • Displays task name, type (SCHEDULED/EVENT/MANUAL), and description
  • Suitable for scenarios with specific business processes
  • Prevents the agent from executing unrelated tasks

5. Data Source Selection Strategy​

○ Do Not Use Data Sources - Disable all data source access
○ All Data Sources - Agent can access all data sources
○ Specified Data Sources - Limited to selected data sources only

Specified Data Source Selection:

  • Controls which data sources the agent can access
  • Displays data source name, operation type (READ/CREATE/UPDATE/DELETE), and description
  • Shows associated database information
  • Suitable for scenarios requiring restricted data access
  • Enhances data security

External MCP Server Configuration​

Adding an External Server​

{
  "name": "Custom Tool Server",
  "endpoint": "https://your-mcp-server.com",
  "apiKey": "your-api-key",
  "description": "Provides specialized tools for a specific domain",
  "tools": ["tool1", "tool2", "tool3"]
}

Configuration Parameter Descriptions:

  • name: Server display name
  • endpoint: MCP server API endpoint
  • apiKey: Access key (optional)
  • description: Server functionality description
  • tools: List of available tools

Tool Analysis and Execution​

Intelligent Tool Analysis​

The system uses large language models to analyze user input and determine whether tools are needed:

Analysis Factors​

  • User Intent: Analyze the user's actual needs
  • Available Tools: Check the current list of available tools
  • Context Information: Leverage knowledge base and search results
  • Execution History: Avoid re-executing the same tools
  • Role Definition: Based on the agent's professional role

Analysis Flow​

User Input → Intent Recognition → Tool Matching → Parameter Generation → Execution Decision

Tool Execution Process​

1. Parameter Validation​

  • Check that all required parameters are present
  • Validate parameter types and formats
  • Apply default values and constraints

2. Permission Check​

  • Verify the user's access permissions for the tool
  • Check space-level tool configuration
  • Ensure compliance with security policies

3. Tool Invocation​

  • Select the invocation method based on tool type
  • Pass complete context information
  • Record the execution process and results

4. Result Processing​

  • Parse the results returned by the tool
  • Generate an execution summary
  • Update tool execution history

Error Recovery Mechanism​

When tool execution fails, the system provides intelligent error recovery:

Error Analysis​

  • Parse the error type and cause
  • Analyze issues with the original parameters
  • Provide parameter correction suggestions

Automatic Retry​

  • Regenerate parameters based on error information
  • Intelligently adjust tool invocation strategies
  • Provide detailed retry reasons

Error Type Handling​

  • Parameter Errors: Re-analyze and generate parameters
  • Permission Errors: Check access configuration
  • Network Errors: Attempt to reconnect
  • Business Errors: Adjust strategy based on error information

Tool Development and Integration​

External MCP Server Development​

Standard MCP Protocol​

  • Implement the standard MCP interface specification
  • Support tool list queries
  • Provide a tool execution interface
  • Return standardized result formats

Server Example​

// Tool list endpoint
GET /tools
{
  "tools": [
    {
      "name": "weather_query",
      "description": "Query weather information",
      "parameters": {...}
    }
  ]
}

// Tool execution endpoint
POST /execute
{
  "tool": "weather_query",
  "parameters": {"city": "Beijing"}
}

API Reference​

List Available Tools​

Retrieve the tools resolved for an agent (built-in tools plus the operators, tasks, data sources, and external tools allowed by its configuration). The space and user are derived from your authentication — no X-Space-ID, X-User-ID, or X-Agent-ID headers are needed.

const res = await fetch(`/api/agents/${agentId}/mcp/tools`, {
  method: 'GET',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY'
  }
});

const { data } = await res.json();
// data: { tools, operatorTools, taskTools, externalTools }

The agent executes these tools itself during a chat or task run (when the thinking chain is enabled); there is no separate "execute tool" endpoint to call directly.

Best Practices​

Tool Selection Strategies​

Specialized Agents​

  • Operator Selection: Use the "Specified Operators" strategy, selecting only operators relevant to the domain
  • Task Selection: Use the "Specified Tasks" strategy, limiting executable task types
  • Data Source Selection: Use the "Specified Data Sources" strategy, limiting accessible data sources
  • Advantages: Improves response accuracy and specialization while enhancing security

General-Purpose Agents​

  • Operator Selection: Use the "All Operators" strategy for broad functional coverage
  • Task Selection: Use the "All Tasks" strategy, allowing execution of any task
  • Data Source Selection: Use the "All Data Sources" strategy, allowing access to all data sources
  • Advantages: Suitable for diverse task requirements, providing maximum flexibility

Data-Intensive Agents​

  • Operator Selection: Select operators related to data processing
  • Data Source Selection: Use the "Specified Data Sources" strategy, selecting required data sources
  • Task Selection: Optionally select data synchronization, data transformation, and similar tasks
  • Advantages: Focused on data processing and analysis tasks

Task Orchestration Agents​

  • Task Selection: Use the "Specified Tasks" strategy, selecting tasks to be orchestrated
  • Operator Selection: Select operators needed for task execution
  • Data Source Selection: Select data sources based on task requirements
  • Advantages: Focused on task orchestration and process automation

Performance Optimization Tips​

Improving Tool Execution Success Rate​

  1. Keep Selections Focused: Grant only the operators, tasks, and data sources the agent actually needs
  2. Optimize Error Handling: Provide clear error messages and recovery suggestions
  3. Monitor Tool Status: Regularly check external server availability

Security Considerations​

Permission Control​

  • Strictly limit tool access permissions
  • Regularly review tool usage
  • Implement the principle of least privilege

Data Protection​

  • Avoid passing sensitive information in tool parameters
  • Use encrypted transmission to protect API communications
  • Log and audit tool invocation records

Troubleshooting​

Common Issues​

Empty Tool List​

Causes:

  • The thinking chain is not enabled for the agent
  • Both the Built-in Tools and Platform Tools toggles are off
  • Incorrect permission configuration

Solutions:

  1. Enable the thinking chain, then open the Tools (MCP) tab
  2. Enable Built-in Tools and/or Platform Tools as needed
  3. Verify user permission settings

Tool Execution Failure​

Causes:

  • Incorrect parameter format
  • Insufficient permissions
  • External service unavailable

Solutions:

  1. Check that parameters meet tool requirements
  2. Verify tool access permissions
  3. Test external server connections

Next Steps​

Explore more related features:

  • Learn about the complete feature set in Agent Overview
  • Study the Tool System for a deep dive into operators
  • Master Workflows to understand task execution flows
  • Explore the Agent API to integrate agents into your applications

Related guides: