API Tool

Create custom tools that call HTTP APIs.

Overview

The API tool type lets you define custom tools that make HTTP requests to external APIs. This is useful for integrating agents with REST APIs, webhooks, or any HTTP-based service without writing code.

When to Use
  • Integrating with REST APIs that don’t have an MCP server
  • Simple HTTP operations (GET, POST)
  • Quick prototyping before building a full MCP server

Configuration

agents:
  assistant:
    model: openai/gpt-4o
    description: Assistant with API access
    instruction: You can look up weather information.
    toolsets:
      - type: api
        api_config:
          name: get_weather
          method: GET
          endpoint: "https://api.weather.example/v1/current?city=${city}"
          instruction: Get current weather for a city
          args:
            city:
              type: string
              description: City name to get weather for
          required: ["city"]
          headers:
            Authorization: "Bearer ${env.WEATHER_API_KEY}"

Properties

The api toolset accepts the following toolset-level fields in addition to the api_config block:

Property Type Required Description
api_config object ✓ The HTTP tool definition. See the table below.
timeout int ✗ HTTP client timeout in seconds (default: 30). Applies to every call the generated tool makes.
allow_private_ips boolean ✗ Opt in to dialling non-public IP addresses (loopback, RFC1918, link-local — including the cloud-metadata endpoint at 169.254.169.254 — multicast and the unspecified address). Set to true only when the configured endpoint legitimately targets internal services. See Reaching internal services.

api_config

Property Type Required Description
name string ✓ Tool name (how the agent references it)
method string ✓ HTTP method: GET or POST
endpoint string ✓ URL endpoint (supports ${param} interpolation)
instruction string ✗ Description shown to the agent
args object ✗ Parameter definitions (JSON Schema properties)
required array ✗ List of required parameter names
headers object ✗ HTTP headers to include. Values support ${env.VAR} and ${headers.NAME} placeholders (the latter forwards a header from the caller’s incoming request, useful when docker agent is itself exposed as an HTTP server).
output_schema object ✗ JSON Schema for the response. Used by MCP / Code Mode consumers; tool responses are still returned to the model as raw strings.

HTTP Methods

GET Requests

For GET requests, parameters are interpolated into the URL:

toolsets:
  - type: api
    api_config:
      name: search_users
      method: GET
      endpoint: "https://api.example.com/users?q=${query}&limit=${limit}"
      instruction: Search for users by name
      args:
        query:
          type: string
          description: Search query
        limit:
          type: integer
          description: Maximum results (default 10)
      required: ["query"]

POST Requests

For POST requests, parameters are sent as JSON in the request body:

toolsets:
  - type: api
    api_config:
      name: create_task
      method: POST
      endpoint: "https://api.example.com/tasks"
      instruction: Create a new task
      args:
        title:
          type: string
          description: Task title
        description:
          type: string
          description: Task description
        priority:
          type: string
          enum: ["low", "medium", "high"]
          description: Task priority
      required: ["title"]
      headers:
        Content-Type: "application/json"
        Authorization: "Bearer ${env.API_TOKEN}"

URL Interpolation

Use ${param} syntax to insert parameter values into URLs:

endpoint: "https://api.example.com/users/${user_id}/posts/${post_id}"

Parameter values are inserted as strings by the template expansion. Add URL encoding in the template when needed (for example, ${encodeURIComponent(city)}).

Headers

Headers can include environment variables:

headers:
  Authorization: "Bearer ${env.API_KEY}"
  X-Custom-Header: "static-value"
  Content-Type: "application/json"

Output Schema

Optionally document the expected response format:

toolsets:
  - type: api
    api_config:
      name: get_user
      method: GET
      endpoint: "https://api.example.com/users/${id}"
      instruction: Get user details by ID
      args:
        id:
          type: string
          description: User ID
      required: ["id"]
      output_schema:
        type: object
        properties:
          id:
            type: string
          name:
            type: string
          email:
            type: string
          created_at:
            type: string

Example: GitHub API

agents:
  github_assistant:
    model: openai/gpt-4o
    description: Assistant that can query GitHub
    instruction: You can look up GitHub repositories and users.
    toolsets:
      - type: api
        api_config:
          name: get_repo
          method: GET
          endpoint: "https://api.github.com/repos/${owner}/${repo}"
          instruction: Get information about a GitHub repository
          args:
            owner:
              type: string
              description: Repository owner (user or org)
            repo:
              type: string
              description: Repository name
          required: ["owner", "repo"]
          headers:
            Accept: "application/vnd.github.v3+json"
            Authorization: "Bearer ${env.GITHUB_TOKEN}"

      - type: api
        api_config:
          name: get_user
          method: GET
          endpoint: "https://api.github.com/users/${username}"
          instruction: Get information about a GitHub user
          args:
            username:
              type: string
              description: GitHub username
          required: ["username"]
          headers:
            Accept: "application/vnd.github.v3+json"

Limitations

Reaching internal services

toolsets:
  - type: api
    timeout: 60
    allow_private_ips: true
    api_config:
      name: get_local_status
      method: GET
      endpoint: "http://localhost:8080/health"
      instruction: Check the local service health
SSRF

Setting allow_private_ips: true re-exposes the SSRF surface for this tool. Only enable it when the configured endpoint is a trusted internal service — a prompt-injected agent cannot redirect the call elsewhere because the endpoint is fixed in config, but redirects from the configured host can still reach unexpected places.

For Complex APIs

For APIs that need authentication flows, pagination, or complex request/response handling, consider using an MCP server instead. The API tool is best for simple, stateless HTTP operations.

Security

API keys and tokens in headers are visible in debug logs. Use environment variables (${env.VAR}) rather than hardcoding secrets in configuration files.

← Previous LSP