Skip to main content
A deployment’s tools come from two places: the built-in Hermes toolset and the MCP servers registered on the deployment. Built-in tools are listed and toggled directly; custom tools are managed through their MCP server.

List tools

GET /v1/deployments/:deployment_id/tools
Returns every tool visible to the agent, with its origin.
const { data } = await herm.tools.list("dep_7xK9s2");
{
  "data": [
    { "name": "shell", "origin": "builtin", "enabled": true },
    { "name": "read_file", "origin": "builtin", "enabled": true },
    { "name": "write_file", "origin": "builtin", "enabled": true },
    { "name": "edit_file", "origin": "builtin", "enabled": true },
    { "name": "web_search", "origin": "builtin", "enabled": true },
    { "name": "browser", "origin": "builtin", "enabled": true },
    { "name": "subagents", "origin": "builtin", "enabled": true },
    { "name": "generate_video", "origin": "mcp:prism-media", "enabled": true },
    { "name": "search_models", "origin": "mcp:prism-media", "enabled": true }
  ]
}

Toggle a built-in tool

PATCH /v1/deployments/:deployment_id/tools/:tool_name
await herm.tools.update("dep_7xK9s2", "browser", { enabled: false });
A disabled tool is invisible to the agent — it isn’t listed, so the model can’t attempt it. MCP tools are toggled via their server’s allowlist below.

Add an MCP server

POST /v1/deployments/:deployment_id/mcp-servers
await herm.mcpServers.add("dep_7xK9s2", {
  name: "acme-crm",
  url: "https://api.acme.com/mcp",
  tools: ["search_contacts", "log_activity"],
});
ParameterTypeRequiredDescription
namestringYesUnique server name per deployment
urlstringYesMCP server URL
toolsstring[]NoAllowlist. Omit to expose all published tools
The server’s tools are available to the agent’s next run.

List MCP servers

GET /v1/deployments/:deployment_id/mcp-servers
const { data } = await herm.mcpServers.list("dep_7xK9s2");
{
  "data": [
    {
      "name": "prism-media",
      "url": "https://api.prismvideos.com/mcp",
      "tools": ["search_models", "generate_image", "generate_video"],
      "status": "connected"
    }
  ]
}
status is connected or unreachable — useful for surfacing integration health in your dashboard.

Update an MCP server

PATCH /v1/deployments/:deployment_id/mcp-servers/:name
Update the URL or allowlist. A common pattern is widening the allowlist when a customer upgrades plans:
await herm.mcpServers.update("dep_7xK9s2", "prism-media", {
  tools: ["search_models", "generate_image", "generate_video", "generate_audio"],
});

Remove an MCP server

DELETE /v1/deployments/:deployment_id/mcp-servers/:name
await herm.mcpServers.remove("dep_7xK9s2", "acme-crm");
All of the server’s tools disappear from the agent immediately.

Errors

StatusErrorWhen
400validation_errorInvalid body, or duplicate server name
404not_foundDeployment, tool, or server does not exist
See Errors for the full error reference.