Skip to main content
Version: v1.6.47-dev1 🚧

Overview

MCP (Model Context Protocol) servers extend Enterprise h2oGPTe agents by providing access to external tools and services through a standardized protocol. This guide explains what MCP servers are and how to configure them in Enterprise h2oGPTe.

What are MCP Servers?​

MCP (Model Context Protocol) is an open standard designed to streamline and unify the way AI agents connect with external tools, APIs, databases, and software services. By acting as a bridge, MCP servers expose a set of functionalities such as data queries, automation tasks, or integration routines to Enterprise h2oGPTe agents in a predictable and secure manner.

This consistent interface allows agents to leverage a wide array of external capabilities, making it easy to add, update, or swap tools as your needs evolve, all without changing your core Enterprise h2oGPTe environment.

How MCP servers work:

  1. Agents discover available tools from MCP servers
  2. Users make requests through the agent interface
  3. Agents call the appropriate MCP tools
  4. MCP servers execute operations and return results
  5. Agents present results in conversational format

Benefits:

  • Standardized integration across different tools
  • Extend agent capabilities with specialized functionality
  • Mix and match different MCP servers as needed
  • Controlled access to external systems

Accessing MCP Tools​

All users can access and configure MCP tools in Enterprise h2oGPTe. To access MCP tools settings:

  1. Navigate to Agents in the main navigation.
  2. Select the Tools tab.
  3. Click New Tool to add a new MCP tool.

From the Tools tab, you can:

  • View all configured MCP tools with details like tool name and owner information
  • Add new local or remote MCP tools
  • Edit existing tool configurations
  • Delete tools you no longer need
  • Manage environment variables for tools

Agent Tools Tab

info

MCP tools are configured per user. Each user can customize which MCP tools are available in their agent conversations. Administrators can control which tools are visible and accessible to users through system settings and permissions, enabling centralized management of tool availability based on organizational policies and security requirements.

Types of MCP Integration​

Enterprise h2oGPTe supports two types of MCP integration:

1. Local MCP Tools​

Custom MCP server implementations that run locally in Enterprise h2oGPTe. Upload ZIP files containing your MCP server implementation.

Requirements:

  • ZIP file containing server.py with MCP protocol implementation; each tool directory must have server.py at its lowest level
  • Optional: envs.json for environment variable definitions
  • Optional: description.md for tool documentation

Use cases:

  • Proprietary integrations (custom in-house tools)
  • Custom business logic
  • Offline functionality
tip

Local MCP tools are ideal for custom integrations that need to run within your Enterprise h2oGPTe environment. They execute directly in the Enterprise h2oGPTe runtime, providing better performance and security for internal tools.

Local MCP Tool Configuration Dialog​

Click + New Tool to open the menu options. From the drop-down, select Local MCP Tools.

Local MCP Tools Menu

The configuration dialog appears:

Upload MCP Tool:

  • Upload a ZIP file containing your MCP tool
  • The ZIP can contain multiple tools, each in separate folders
  • Each folder must contain server.py at its root level
  • Optional files: envs.json and description.md

MCP Usage Mode:

  • Runner: Tool executes actions and provides data during conversations (default)
  • Creator: Tool helps build or generate other tools or content programmatically
tip
  • You can select one or both modes. Most tools work best in Runner mode.
  • Use Creator mode for tools that generate code, create files, or build other tools programmatically.
  • If uploading multiple tools in a ZIP, the selected mode applies to all tools in that group.

Persistent Tool (if available):

  • Ephemeral tools run only when needed
  • Persistent tools stay active until terminated

Enable by Default:

  • When enabled, the tool is automatically available in agent conversations
  • When disabled, you must manually enable it per conversation

Click Add Tool to add the local MCP tool to Enterprise h2oGPTe.

Local MCP Tool Configuration Dialog

2. Remote MCP Tools​

MCP servers accessed over the network. Configure using JSON in the Enterprise h2oGPTe UI.

Configuration:

  • JSON-based setup
  • Multiple transport options: stdio, HTTP, SSE
  • Environment variable management for credentials

Use cases:

  • External service integrations
  • Community MCP servers
  • Cloud-based tools
info

Remote MCP tools connect to external MCP servers over the network. They support multiple transport protocols (stdio, HTTP, SSE) and can integrate with any MCP-compatible server.

Remote MCP Tool Configuration Dialog​

Click + New Tool to open the menu options. From the drop-down, select Remote MCP Tools.

Remote MCP Tools Menu

MCP Configuration JSON:

  • Enter JSON configuration in standard MCP format or simplified format
  • Supports both single and multiple tools
  • Optional fields use system defaults if not specified

Configuration format options:

Standard format with mcpServers wrapper:

{
  "mcpServers": {
    "tool-name": {
      "command": "executable",
      "args": ["arg1", "arg2"],
      "env": {
        "API_KEY": "os.environ/API_KEY"
      }
    }
  }
}

Simplified format (without wrapper):

{
  "tool-name": {
    "command": "executable",
    "args": ["arg1", "arg2"],
    "env": {
      "API_KEY": "os.environ/API_KEY"
    }
  }
}

Configuration fields:

  • command: Executable command to run (required if url is not specified)
  • url: Server URL (required if command is not specified)
  • args: Array of command arguments (optional)
  • env: Environment variables using os.environ/VARIABLE_NAME syntax (optional)
  • description: Tool description (optional, but recommended)
  • tool_usage_mode: Array with ["runner"], ["creator"], or both (optional, defaults to both)
  • transport: Transport protocol - stdio, http, or sse (optional)

Tool Usage Modes:

  • Runner: Tool executes actions and provides data during conversations (default)
  • Creator: Tool helps build or generate other tools or content programmatically

Enable by Default:

  • When enabled, the tool is automatically available in agent conversations
  • When disabled, you must manually enable it per conversation

The Connect Remote MCP Server dialog box provides real-time JSON validation with error messages and suggestions for improvements.

Click Add Tool to add the remote MCP tool to Enterprise h2oGPTe.

Remote MCP Tool Configuration Dialog

tip

You can configure multiple MCP servers in a single JSON configuration. Each server in the configuration becomes a separate tool that agents can use.

How Agents Use MCP Tools​

Enterprise h2oGPTe agents automatically discover and use MCP tools based on the context of user requests. When you interact with an agent:

  1. Core initializes agent with available tools: The system loads all configured MCP tools that are enabled for your user account (either enabled by default or manually selected)
  2. Agent sends request to LLM with tool definitions: Your request is sent to the language model along with descriptions of all available MCP tools
  3. LLM analyzes request and selects tools: The language model analyzes your request and automatically selects which MCP tools to invoke based on tool descriptions, capabilities, and request context
  4. Tools execute and return results: Selected MCP tools execute their operations and return results back to the agent
  5. Agent iteratively uses tools as needed: The agent may invoke additional tools in subsequent turns based on previous results, creating a multi-step workflow
  6. Agent combines results and presents final response: Tool results are combined and formatted into a conversational response presented to you

Example workflows:

  • Data analysis: Agent uses a database MCP tool (e.g., MongoDB Atlas) to query data, then uses a visualization tool to create charts
  • Content creation: Agent uses a document MCP tool (e.g., Google Docs) to create content, then uses a collaboration tool (e.g., Slack) to share it
  • Research tasks: Agent uses a search MCP tool (e.g., Bing Search) to find information, then uses a summarization tool to present findings

Tool selection:

Agents automatically select the most appropriate tools based on:

  • Tool descriptions and capabilities
  • User request context
  • Tool availability and permissions
  • Tool usage mode settings (Runner or Creator)
tip

Enable tools by default for frequently used integrations. This allows agents to automatically use them without manual selection in each conversation. For sensitive or specialized tools, disable "Enable by Default" and manually enable them when needed.

Security Considerations​

API key management:

  • Store credentials in Agents > Authentication, not in configuration files
  • Use os.environ/VARIABLE_NAME syntax to reference variables
  • Rotate keys regularly
  • Use least privilege access

Access control:

  • User permissions are validated before tool execution
  • Tool-specific access restrictions apply
  • Network security policies apply to remote servers
warning

Never hardcode API keys or credentials in MCP tool configuration files. Always use the os.environ/VARIABLE_NAME syntax to reference environment variables stored securely in Agents > Authentication.

What's Next?​

Feedback