---
title: "Add Custom Agent Tools"
method: POST
path: "/agents/custom_tools"
tags: ["Agents"]
---

# Add Custom Agent Tools

`POST /agents/custom_tools`

## Request

- Base URL: `https://h2ogpte.genai.h2o.ai/api/v1`
- URL: `https://h2ogpte.genai.h2o.ai/api/v1/agents/custom_tools`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/h2o/apis/h2ogpte-rest-api/docs/agents/custom_tools/post.ts> (a function with typed inputs; its response is checked against the schema)

Add Custom Agent Tools

## Request body `multipart/form-data`

- object
  - `file` string, binary, nullable: The tool file to upload. Requirements vary by tool_type: - local_mcp: .zip file containing MCP server code - remote_mcp: Optional configuration file — any extension accepted (common: .json, .yml, .yaml, .py, .zip, .toml, .ini, .conf, .config, .env, .txt) - browser_action: .py file (must start with 'browser_') or .zip containing browser action scripts - general_code: .py or .zip file with custom code
  - `tool_type` 'local_mcp' | 'remote_mcp' | 'browser_action' | 'general_code', required: The type of custom tool being added: - local_mcp: Model Context Protocol server running locally - remote_mcp: Model Context Protocol server running remotely - browser_action: Custom browser automation actions - general_code: General purpose code execution tools
  - `tool_args` string, required: JSON string containing tool-specific arguments. The structure varies by tool_type: For remote_mcp: { "mcp_config_json": "JSON string with MCP server configuration", "enable_by_default": true/false (optional, defaults to true) } For local_mcp, browser_action, and general_code: { "tool_name": "string (optional, defaults to filename without extension)", "description": "string (optional, tool description)", "enable_by_default": true/false (optional, defaults to true), "should_unzip": true/false (optional, for general_code .zip files only), "tool_usage_mode": ["runner", "creator"] (optional list of strings), "system_prompt": "string (automatically added when generate_system_prompt=true)" }
  - `custom_tool_path` string, nullable
  - `filename` string, nullable: Optional filename to use when storing the uploaded file
  - `generate_system_prompt` boolean, nullable: If true and tool_type is "general_code", generates a system prompt for the tool using LLM analysis. The generated system prompt will be automatically added to tool_args["system_prompt"] after generation completes. Only valid for general_code tool type. WARNING: This is a long-running synchronous operation. The server holds the HTTP connection open while the LLM analyzes the uploaded code. Ensure your HTTP client timeout and any intermediate proxies (nginx, ALB, Cloudflare, etc.) are configured with sufficient timeout. Default proxy timeouts of 60-120s will cause 504 Gateway Timeout errors. See `system_prompt_generation_timeout` to constrain the wait budget on the server side.
  - `system_prompt_generation_timeout` number, double, nullable: Optional wait budget in seconds for synchronous system prompt generation (only used when generate_system_prompt is true). Set this below your proxy/ingress read timeout so the API returns a 408 instead of letting the proxy emit a 504. If omitted, defaults to the server-side cap of 600 seconds (10 minutes).

## Response `201`

Custom agent tool created successfully

- object[]
  - `agent_custom_tool_id` string: The ID of the created custom agent tool

## Other responses

- `400`: Bad request
- `401`: Unauthorized - Invalid or missing API key
- `415`: Unsupported media type
- `default`: Unexpected error

---

[API](https://skmtc.dev/h2o/apis/h2ogpte-rest-api.md) - [All operations](https://skmtc.dev/h2o/apis/h2ogpte-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/h2o/apis/h2ogpte-rest-api/revisions/a82a117320f4?raw)