Deploy a custom agent with a local MCP tool

This tutorial explains how to generate and deploy a local MCP tool and a custom agent in Enterprise h2oGPTe. You will create both packages in h2oGPTe Chat, register them, configure mappings when needed, and validate the workflow in h2oGPTe Chat. This tutorial uses a weather assistant example. The custom agent receives a weather question, calls the MCP tool, and returns a structured response. You can apply the same process to other use cases.

After you complete this tutorial, you can:

• Generate a local MCP tool package with Tool Builder.
• Generate a custom agent package with Agents Builder.
• Upload and connect both packages in Agents > Tools and Agents > Agents.
• Test the connected workflow in h2oGPTe Chat.

Prerequisites

Before you begin, confirm the following:

• You can sign in to Enterprise h2oGPTe.
• Your workspace has access to both Tool Builder and Agents Builder.
• You have read Custom agents for the Agents page layout and actions.
• You have a secret for your model provider API key in Secret Manager.

Step 1: Generate the local MCP tool package with Tool Builder

1. Open h2oGPTe > Chat.
2. Select Tool Builder from the agent selector.
3. Open Tool Types, then select Local MCP.
4. Enter a prompt that defines your MCP tool and server name.
5. Download the generated MCP tool package as a .zip file.

For this use case, include the following in your prompt:

- The MCP server name `weather-mcp`.
- The required file `server.py`.
- A single MCP tool named `get_weather(city: str) -> str`.
- Input validation requirements for `city`.
- Output format requirements for the returned weather summary.
- The optional file `description.md`.
- A statement that the tool does not require environment variables.
- A request to return a downloadable `.zip` package.

Note

For UI steps, packaging requirements, and troubleshooting, see Create local MCP tools.

Step 2: Generate the custom agent package with Agents Builder

1. In h2oGPTe > Chat, select Agents Builder from the agent selector.
2. Describe a custom agent that calls the weather-mcp MCP server.
3. Set the builder accuracy mode based on your use case:
   • Quick for fast iteration.
   • Basic for balanced speed and quality.
   • Standard for default quality-focused generation.
   • Maximum for deeper research and richer output.
4. Open the generated package preview, then verify the environment variable section includes your required provider keys (for example, CUSTOM_AGENT_API_KEY and CUSTOM_AGENT_BASE_URL).
5. Verify the generated package includes required agent files:
   • custom_agents.py
   • metadata.json
   • requirements.txt
   • envs.json
6. Download the generated custom agent package as a .zip file.

For this use case, include the following in your prompt:

- The agent framework `langgraph`.
- A requirement to call the MCP server name `weather-mcp`.
- The MCP tool name `get_weather(city: str) -> str`.
- A requirement to extract one or more city names from a user question.
- A requirement to handle multi-city questions.
- Output format requirements for the final agent response.
- Required environment variables:
  - `CUSTOM_AGENT_API_KEY`
  - `CUSTOM_AGENT_BASE_URL`
- Optional environment variables:
  - `CUSTOM_AGENT_MODEL`
  - `CUSTOM_AGENT_TIMEOUT`
- Return a downloadable `.zip` package compatible with **Agents > Agents**.

Step 3: Upload the local MCP tool package

1. In the left navigation, open Agents > Tools.

2. Click + Custom Tool. The Upload Local MCP Tool dialog opens.

3. Upload the MCP tool .zip file you generated.

4. Under Sub-tools, verify that your tool and its capabilities are listed and selected.

5. Configure tool settings:

   • Under MCP Usage Mode, select both Runner (executes actions during conversations) and Creator (builds or generates other tools).
   • Keep Enable by Default enabled.

   

6. Click Add Tool.

7. Verify that the tool appears in the Tools table with a green status indicator.

Step 4: Register the custom agent

1. Open Agents > Agents.

2. Click + New Agent.

3. Enter an agent name.

4. Upload the custom agent .zip file you generated.

   

5. Click Add Agent.

6. Verify that the agent appears in the Agents table.

   

Step 5: Assign required keys and tools

Note

Complete this step only if your custom agent requires API keys, MCP tools, or both. If your custom agent does not depend on keys or tools, continue to Step 6.

1. Open the new agent action menu, then select Assign Keys.
2. Map required values:
   • CUSTOM_AGENT_API_KEY to your model provider secret.
   • CUSTOM_AGENT_BASE_URL to a secret that stores the provider base URL.

3. Save key mappings.
4. Open the action menu again, then select Assign Tools.
5. Map weather-mcp to the MCP tool you uploaded.

6. Save the tool mapping.
7. Verify that the agent status in the Agents table shows Ready.

Step 6: Test the workflow

1. Start a new chat.
2. Select the newly registered custom agent.

3. Send a weather request, for example:
   • What is the weather in Tokyo?
   • Compare weather in London and Paris.
4. Confirm the response includes structured output.

Verification checklist

• The agent responds without configuration errors.
• The response includes the expected output for your use case.
• Tool invocation completes during the same chat turn.

Next steps

• Build additional MCP tools by following Create local MCP tools.
• Automate registration flows with the Custom Tools API.
• Automate agent lifecycle with the Custom Agents API.

---

Feedback

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