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 external functions and services. GeniSpace implements a complete MCP tool ecosystem, including:

  • Built-in Tools: Standardized tools provided through the platform tool system
  • External Tools: Third-party tools provided through MCP servers
  • Intelligent Routing: Automatic identification and routing to the correct tool server

Tool Categories​

Built-in Tools​

  • Source: Platform built-in tool system
  • Types: HTML rendering, chart generation, table display, etc.
  • Invocation Method: Unified interface through mcp-server
  • Caching Strategy: 10-minute TTL, session + agent-based
  • Permission Control: Can be enabled or disabled via configuration

Platform Operator Tools​

  • Source: Platform operator system and user-defined custom operators
  • Invocation Method: Unified interface through mcp-server
  • Naming Convention: operator_identifier_method_identifier
  • Caching Strategy: 10-minute TTL, session + agent-based
  • 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
  • Caching Strategy: 5-minute TTL, globally shared
  • Extensibility: Supports any number of external servers

MCP Tool Configuration​

Basic Configuration​

Configure in the "MCP Tools" section of the agent configuration page:

1. Enable MCP Tools​

☑️ Enable MCP Tool Invocation
  • Controls whether the agent can use MCP tools
  • When disabled, the agent cannot invoke any tools

2. Built-in Tools Configuration​

☑️ Enable Built-in Tools
  • Controls whether platform built-in tools are enabled
  • Includes database queries, email sending, file processing, etc.

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

Intelligent Tool Routing System​

Tool Source Mapping​

GeniSpace uses an intelligent routing architecture that automatically builds a tool source mapping table:

{
  "tool_name": {
    "type": "builtin|external",
    "server_name": "mcp-server|custom-server"
  }
}

Routing Strategies​

// The agent automatically selects the most appropriate tool
await execute_tool("query_database", parameters, "auto");

Specified Type Routing​

// Force use of built-in tool
await execute_tool("query_database", parameters, "builtin");

// Force use of external tool
await execute_tool("custom_analysis", parameters, "external");

Fallback Mechanism​

When intelligent routing fails, the system activates a fallback mechanism:

  1. First attempts built-in tools
  2. Then attempts external tools
  3. Returns detailed error information

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 team-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

Caching and Performance Optimization​

Multi-Layer Caching Architecture​

Built-in Tool Cache​

  • TTL: 10 minutes (5–10 minute range)
  • Key Strategy: {session_id}:{agent_id}
  • Stored Content: Tool list and metadata
  • Use Case: Tools that are relatively stable

External Tool Cache​

  • TTL: 5 minutes (2–5 minute range)
  • Key Strategy: external_tools (global)
  • Stored Content: External server tool lists
  • Use Case: External tools that may change frequently

Session Cache​

  • TTL: 30 minutes
  • Key Strategy: {team_id}:{user_id}:{agent_id}
  • Stored Content: MCP session IDs
  • Use Case: Maintaining session state

Cache Management​

Automatic Expiration​

// Cache automatically checks expiration time
{
  "data": tools_list,
  "expires_at": timestamp
}

Manual Clearing​

// Clear cache for a specific agent
clear_cache_for_agent(agent_id);

// Clear all cache
clear_cache("all");

// Clear specific cache type
clear_cache("builtin|external|sessions");

Cache Statistics​

{
  "builtin_tools": {"total": 15, "expired": 2, "valid": 13},
  "external_tools": {"total": 8, "expired": 0, "valid": 8},
  "sessions": {"total": 5, "expired": 1, "valid": 4}
}

Display Plugin System​

Plugin Overview​

Agents support a powerful display plugin system for customizing how tool output results are rendered:

  • Local Plugins: Built into the system, such as expense reimbursement, travel expenses, etc.
  • Remote Plugins: Standalone plugin projects dynamically loaded via URL
  • Auto-Discovery: Supports automatic plugin discovery and registration
  • Hot Reloading: Supports plugin hot-reload in development mode

Plugin Types​

Local Plugins​

  • Location: Built into the chat system
  • Loading Method: Auto-loaded, no configuration needed
  • Examples: Expense reimbursement plugin, travel expense plugin, URL redirect plugin, iframe embedding plugin

Remote Plugins​

  • Loading Method: Dynamically loaded via HTTP URL
  • Deployment Locations: GitHub Pages, CDN, self-hosted servers, enterprise intranets
  • Advantages:
    • No need to redeploy the chat system
    • Independent version management
    • Supports enterprise customization
    • Can be deployed to intranet environments

Plugin Configuration​

In the agent configuration, display plugins can be configured in the following ways:

  1. Auto-Loading: Automatically loads when tool output contains a plugin URL
  2. Manual Loading: Load remote plugins manually via API
  3. Plugin Whitelist: Configure allowed plugin URLs

Plugin Development​

For detailed plugin development guides, see:

Tool Development and Integration​

Built-in Tool Development​

Tool Specification​

  • Naming Format: {operator_id}_{method_id}
  • Parameter Definition: Uses JSON Schema
  • Return Format: Standardized MCP response format
  • Documentation Requirements: Detailed functionality and parameter descriptions

Example Tool​

{
  "name": "database_query_sql",
  "description": "Execute SQL queries to retrieve database data",
  "inputSchema": {
    "type": "object",
    "properties": {
      "sql": {
        "type": "string",
        "description": "The SQL query statement to execute"
      },
      "database": {
        "type": "string", 
        "description": "Target database name"
      }
    },
    "required": ["sql"]
  }
}

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​

Get Available Tools​

const tools = await fetch('/developer/api-agents/mcp/tools', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'X-Team-ID': team_id,
    'X-User-ID': user_id,
    'X-Agent-ID': agent_id
  }
});

Execute a Tool​

const result = await fetch('/developer/api-agents/mcp/execute', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    toolName: 'database_query_sql',
    parameters: {sql: 'SELECT * FROM users LIMIT 10'},
    toolType: 'auto'
  })
});

Clear Tool Cache​

await fetch(`/developer/api-agents/${agentId}/mcp/cache`, {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

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​

Reducing Tool Invocation Latency​

  1. Configure Cache TTL Appropriately: Balance data freshness and performance
  2. Warm Up Cache: Pre-load commonly used tools when the agent starts
  3. Batch Operations: Merge multiple related operations into a single tool invocation

Improving Tool Execution Success Rate​

  1. Thorough Parameter Validation: Perform initial parameter checks on the client side
  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:

  • MCP functionality is disabled
  • Cache expired or corrupted
  • Incorrect permission configuration

Solutions:

  1. Check that MCP configuration is enabled
  2. Clear and rebuild cache
  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

Performance Issues​

Causes:

  • Low cache hit rate
  • Slow external service responses
  • Excessive tool invocation frequency

Solutions:

  1. Optimize caching strategy
  2. Monitor external service performance
  3. Implement invocation rate limiting

Debugging Tools​

Cache Statistics​

// Get detailed cache statistics
const stats = await getCacheStats();
console.log('Cache statistics:', stats);

Tool Source Mapping​

// View tool routing mapping table
const mapping = await getToolSourceStats();
console.log('Tool mapping:', mapping);

Execution Logs​

// Check tool execution history
const history = await getToolExecutionHistory(agentId);
console.log('Execution history:', history);

Next Steps​

Explore more related features:

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

Related guides: