Custom HTTP tools

Not every capability you want to give an agent lives behind an existing MCP server. Custom HTTP tools let you wrap a plain HTTP endpoint as an MCP tool, so an internal API becomes callable by any client connected to the Virtual MCP.

When to use them

Use a custom HTTP tool when:

  • You have an internal or third-party REST API you want an agent to call.
  • The API does not ship an MCP server of its own.
  • You want tight control over the exact request the agent can make.

For a full MCP server you already run, register it as a connector instead.

Defining a tool

A custom HTTP tool describes the request the gateway will make on the agent’s behalf:

  • Name and description: what the agent sees in tools/list. A clear description is the most important factor in whether the model uses the tool correctly.
  • Method and URL: the HTTP method and endpoint to call. URLs support parameter placeholders.
  • Input schema: the parameters the agent must provide, mapped into the path, query string, headers, or body.
  • Authentication: static headers (for example an API key) applied to every call.

When the agent invokes the tool, the gateway builds the request from the schema-validated arguments, calls the endpoint, and returns the response body as the tool result.

Security notes

  • Scope each tool to the narrowest endpoint that does the job. Prefer a specific path over a broad, templated URL.
  • Keep credentials in the tool’s header configuration rather than embedding them in the URL.
  • Custom HTTP tools run with whatever access their configured credentials grant. Treat them like any other credential you hand to an agent.

Next steps