Skip to main content
Version: v1.7.0

Create remote MCP tools

This guide walks you through creating a Remote MCP tool by setting up an external MCP server connection in Enterprise h2oGPTe, enabling and using it within your agent conversations.

Overview​

Remote MCP tools are accessed over the network and can be configured using the standard MCP tool configuration JSON format, with extra fields specific to Enterprise h2oGPTe: tool_usage_mode and description. It supports various transport protocols like stdio, HTTP, and SSE, and can work with any MCP-compatible server. In most cases, you can copy the JSON configuration from an MCP server README and paste it directly into Enterprise h2oGPTe.

Prerequisites​

  • Access to Enterprise h2oGPTe
  • An external MCP server to connect to (either self-hosted or from the community)
  • API keys or credentials for the MCP server (if required)
  • Basic understanding of MCP (Model Context Protocol). See the Remote MCP Tools overview for more details.

Step 1: Prepare your MCP server configuration​

Before adding a remote MCP tool, make sure you have the following information about your MCP server:

  • Command or URL: The executable command to run the server, or the server URL
  • Type protocol: stdio, HTTP, or SSE
  • Arguments: Any command-line arguments required
  • Environment variables: API keys, tokens, or other credentials needed

Example configurations:

{
  "slack": {
    "command": "npx",
    "args": [
      "-y",
      "slack-mcp-server@latest",
      "--transport",
      "stdio"
    ],
    "env": {
      "SLACK_MCP_XOXP_TOKEN": "os.environ/SLACK_MCP_XOXP_TOKEN"
    }
  }
}

Step 2: Set up Authentication​

  1. In the main navigation, click Agents > Authentication.

  2. Add the required environment variables for your MCP server. Create Key Button

  3. Click + Create Key to open the dialog. Add agent key dialog

    Configure the following fields:

    • Secret reference name (required): The name you will reference in tool configurations (for example, SLACK_MCP_XOXP_TOKEN or HF_TOKEN).
    • Key value (required): The secret value.
    • Description (optional): Add context for other admins.
    • Key type: Select Private (only you) or Shared (all users).

  4. Click Save to store the credentials securely.

caution
  • Do not hardcode API keys or credentials in your JSON configuration.
  • Always use the os.environ/VARIABLE_NAME syntax to reference environment variables.
  • Store all sensitive credentials in Agents > Authentication before configuring the tool.

Step 3: Add your remote MCP tool​

  1. In the main navigation, click Agents > Tools.

  2. Click + New Tool

  3. Select Remote MCP Tools from the dropdown menu. Remote MCP Tools Menu

  4. Enter your JSON configuration in the MCP Configuration JSON field.

    tip

    You can often copy a configuration directly from an MCP server README.

    Example: Hugging Face MCP server

    Paste the following configuration:

    {
      "mcpServers": {
        "huggingface": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "https://huggingface.co/mcp",
            "--header",
            "Authorization: Bearer os.environ/HF_TOKEN"
          ],
          "env": {
            "HF_TOKEN": "os.environ/HF_TOKEN"
          }
        }
      }
    }

  5. Review the JSON validation messages. If your configuration does not include tool_usage_mode or description, the dialog may suggest adding them.

    Remote MCP Tool Configuration Dialog

  6. Configure tool settings:

    • Enable by Default: Choose whether to enable the tool automatically in conversations

  7. Click Add Tool

Configuration fields:

  • command: Executable command to run (required if url is not specified)
  • url: Server URL for HTTP or SSE transport (required if command is not specified)
  • args: Array of command arguments (optional)
  • env: Environment variables using os.environ/VARIABLE_NAME syntax (optional). The variable name must match in three places: the env object key, the variable name in os.environ/VARIABLE_NAME, and the secret reference name in Agents > Authentication (e.g., "HF_TOKEN": "os.environ/HF_TOKEN" requires HF_TOKEN in all three locations)
  • headers: HTTP headers for HTTP or SSE transport (optional, used with url)
  • description: Tool description (optional, but recommended)
  • tool_usage_mode: Array with ["runner"], ["creator"], or both (optional, defaults to ["runner", "creator"]). Use ["runner"] for tools that execute actions and provide data during conversations (most common). Use ["creator"] for tools that generate code, create files, or build other tools programmatically. Use both when the tool supports both use cases.
  • Type: Transport protocol - stdio, http, or sse (optional)
  • You can configure multiple MCP servers in a single JSON configuration.
  • Each server in the configuration becomes a separate tool that agents can use.

Expected result: Your remote MCP tool appears in Agents > Tools and is ready to enable in conversations.

Step 4: Enable and test your tool.​

  1. Go to a new chat session.
  2. Select your preferred agent (e.g., General Agent or another agent)
  3. Open Agent Configuration (⚙️ gear icon or Settings button)
  4. Navigate to the Custom Tools section
  5. Enable your remote MCP tool by toggling it on in the list
  6. Send a test message and verify the response

Use the following prompts to test your tool:

Slack MCP tool:

  • "Send a message to #general channel saying 'Hello from Enterprise h2oGPTe'"
  • "What are the last 5 messages in #general channel?"

Hugging Face MCP tool:

  • "Find me a text classification model on Hugging Face"
  • "What information can you provide about the bert-base-uncased model?"

Remote Hugging Face MCP Tool Example

The screenshot above shows a successful Hugging Face MCP tool execution in a chat session.

Step 5: Verify Tool Execution​

After you send your message, confirm that:

  • The tool runs successfully.
  • The response contains the expected data.
  • Errors are handled as expected.

Test common error scenarios:

  • Invalid API keys or authentication failures
  • Network connection errors
  • Malformed requests or invalid parameters

Next Steps​

Feedback