Skip to main content

Turn an API into a tool by asking your agent

When your agent needs to reach an HTTP API it has no tool for, you don't have to build the connector yourself. Describe the API and let the agent create a custom tool with create_custom_tool — after which it calls the API like any other tool.

The steps​

  1. Describe the endpoint. Tell the agent the request shape: the HTTP method, the URL (with which parts come from arguments), what inputs it takes, and whether it needs authentication.
  2. Let the agent create the tool. It calls create_custom_tool with a connector definition and a JSON-Schema description of the arguments. Use a bare name with a standalone personal credential, me/name for the represented member's private organization space, or <team>/name for a bound team. A bare organization-scoped name denotes the read-only organization catalogue.
  3. Add a secret if the API needs one. For any authenticated API the tool is created disabled, because secrets are never set over MCP — a person adds the token, key, or password and enables the tool in the dashboard. A tool for an API that needs no auth skips the secret step; its initial enabled state follows the owner's default setting. For the security details, see Connect an authenticated API securely.
  4. Use it. Once enabled, the tool appears on the MCP tools surface for credentials that can reach it, alongside the built-in tools. The agent calls it with tools/call.
  5. Fix it in place if a call fails. If the API returns an error, have the agent adjust the connector with update_custom_tool — the same session-driven loop as prompts.

Example​

You want the agent to fetch weather. You tell it:

Create a custom tool called weather that does a GET to https://api.example.com/weather/{city}, takes a required city string, and authenticates with a bearer token.

The agent calls create_custom_tool:

{
	"name": "weather",
	"description": "Fetch the current weather for a city",
	"connector": {
		"http_method": "GET",
		"url_template": "https://api.example.com/weather/{city}",
		"input_schema": {
			"type": "object",
			"properties": { "city": { "type": "string" } },
			"required": ["city"]
		},
		"auth": { "type": "bearer" }
	}
}

Because it uses bearer auth, the tool comes back disabled. Add the token and enable the tool in the dashboard; a credential that can reach it can then call it.

Good to know​

  • Only public endpoints. Custom-tool connectors may call public HTTP/HTTPS URLs only; private, loopback, and cloud-metadata addresses are rejected. See Custom Tools → Safe by construction.
  • Your plan caps how many custom tools you can create — see Plans & Limits.
  • Publishing to the organization catalogue stays a dashboard action; an agent creates custom tools in a represented member's personal space or in a team space its credential can manage.