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
• Select specific sub-tools from an MCP server

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.

Sub-tool selection

You can use sub-tool selection with both local and remote MCP tools. For background on tool types, see Types of MCP integration.

MCP servers expose multiple tools. For example, a Playwright server provides browser_click, browser_type, browser_snapshot, and many others. By default, all tools from a server are available to the agent. Use sub-tool selection to enable only the tools you need and reduce unnecessary tool calls.

You can select sub-tools in three ways:

1. During local tool creation: after uploading the ZIP file, Enterprise h2oGPTe automatically discovers available tools from your package. Select or clear individual tools from the list.
2. During remote tool creation or editing: a Sub-tools section appears below the JSON configuration. Click Refresh sub-tools to list available tools from the server, then select or clear individual tools.
3. From the Tools table: click the actions menu (three dots) on a custom MCP tool row, then click Select Sub-tools to open a quick selection dialog.

If you do not change the default selection, all discovered tools remain available.

Error and empty states

• If discovery fails because the server is unreachable or authentication fails, an error message appears. Verify your server configuration and credentials.
• If the server returns zero tools, a message indicates no tools were found.

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 an MCP entry point: server.py (Python), index.ts (TypeScript), or index.js (JavaScript); each tool directory must have one of these at its lowest level
• Optional: envs.json for environment variable definitions
• Optional: description.md for tool documentation

Multi-tool archives:

• ZIP files can contain multiple tool directories, each with its own entry point
• During upload, Enterprise h2oGPTe automatically discovers all sub-tools in the archive
• You can select which sub-tools to enable before saving—deselected tools do not appear in agent conversations
• Limits: 100 MB maximum upload size, up to 20 sub-directories per archive

note

Each tool directory within the archive is limited to 500 files and 50 MB.

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.

The configuration dialog appears:

Upload MCP Tool:

• Upload a ZIP file containing your MCP tool (maximum 100 MB)
• The ZIP can contain multiple tools, each in separate folders
• Each folder must contain an MCP entry point at its root level: server.py, index.ts, or index.js
• Optional files: envs.json and description.md
• After uploading, sub-tool discovery runs automatically—select which tools to enable using the checkboxes that appear

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

Sub-tool discovery:

When you upload a ZIP file, Enterprise h2oGPTe automatically inspects the package and discovers all available sub-tools. Each discovered tool appears as a checkbox so you can select which ones to enable. If no sub-tools are discovered, all tools in the package are enabled by default.

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

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.

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)
• allowed_tools: Array of tool names to enable (optional). When set, limits agent access to only the specified tools. The sub-tool selection UI populates this field automatically when you select sub-tools.
• type: 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

tip

Use standard launchers like uvx, npx, or python as the command instead of running MCP server binaries directly. This ensures the correct runtime environment is available.

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

After entering a configuration, click Refresh sub-tools to inspect the server and view its available sub-tools before adding. For existing tools that require authentication (using os.environ/ references), the server resolves environment variables securely—no secrets are exposed to the browser.

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

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.

Access MCP tools with the Python SDK

You can manage MCP tools programmatically using the h2oGPTe Python client library. The following methods are available:

• inspect_mcp_tool: perform live discovery against any server, file, or existing tool (with optional security analysis)
• list_mcp_tools: query tools from already-configured servers

Inspect an MCP tool

inspect_mcp_tool() is a unified method that supports three modes. Provide exactly one of tool_id, servers, or file_path. You can optionally pass model to specify which LLM runs the security inspection.

Inspect a remote server before adding it:

result = client.inspect_mcp_tool(
    servers={"playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]}},
)
for srv in result["servers"]:
    print(f"{srv['server_name']}: {srv['tool_count']} tools")
    for tool in srv.get("tools", []):
        print(f"  {tool['name']}: {tool.get('description', '')}")
    if srv.get("security"):
        print(f"  Security rating: {srv['security']['llm_security_rating']}")

Inspect a local MCP package file before adding it:

file_path accepts a .py file, a .zip archive, or a .tar.gz archive:

result = client.inspect_mcp_tool(file_path="./my_mcp_server.py")
# Also valid:
# result = client.inspect_mcp_tool(file_path="./my_mcp_server.zip")
# result = client.inspect_mcp_tool(file_path="./my_mcp_server.tar.gz")
for srv in result["servers"]:
    print(f"{srv['server_name']}: {srv['tool_count']} tools")
    if srv.get("security"):
        print(f"  Security: {srv['security']['llm_security_rating']}")

Inspect an existing tool by ID:

result = client.inspect_mcp_tool(tool_id="abc-123")
for srv in result["servers"]:
    print(f"{srv['server_name']}: {srv['tool_count']} tools")

List tools from configured servers

List all tools available from your configured MCP servers:

result = client.list_mcp_tools(config_type="runner")
for server, info in result.get("servers", {}).items():
    print(f"{server}: {info['tool_count']} tools")

• config_type: "runner" (tools for conversations) or "creator" (tools for building). Defaults to "runner".
• include_remote: Whether to include remote MCP servers. Defaults to True.
• server_names: Optional list of server name strings to filter results to specific servers.

What's next?

• MCP server directory - Browse and configure MCP servers
• Agent tool configuration - Built-in agent tools

---

Feedback

• Submit and view feedback for this page
• Send feedback about Enterprise h2oGPTe to cloud-feedback@h2o.ai