Custom HTTP Connector

Users can add a custom HTTP connector in AgentBlit by exposing REST endpoints on a publicly accessible URL, then registering that URL in the AgentBlit console.

Overview

A custom HTTP connector lets your backend expose tools that agents can discover and invoke. AgentBlit calls your service to list tools, execute them, and optionally load interactive UI. Authentication uses an API key that the user pastes when connecting the tool to an agent.

The flow has two parts:

Build — Implement the required endpoints (and any optional ones you need), then deploy them on a public HTTPS URL. Provide a dashboard where users configure entities and mint API keys.
Register — Add the connector URL (and optional dashboard URL) in the AgentBlit console, then attach it to an agent by pasting the API key.

AgentBlit always appends fixed paths under your base URL:

Endpoint	Method	Required	Auth
`/api/1.0/tools/list`	`GET`	Yes	`X-API-Key`
`/api/1.0/tools/call`	`POST`	Yes	`X-API-Key`
`/api/1.0/resources/read`	`GET`	Only if tools declare UI	`X-API-Key`

The appointment-tool project is a full reference implementation of this contract.

API key auth

AgentBlit stores the connector API key (encrypted) per agent connection and sends it on all runtime calls:

X-API-Key: <connector-api-key>

Endpoint	Header
`tools/list`	Required (also used to verify the key on connect/reconnect)
`tools/call`	Required
`resources/read`	Required

Issue API keys from your connector dashboard. Use the key as your tenancy key (config, bookings, etc.). Return HTTP 401 when the key is missing or invalid.

Build a custom connector

API types

Use these types in your connector service. parameters is a JSON Schema object and varies per tool. Expand a language below to copy the types.

1. List tools

GET /api/1.0/tools/list

Returns the list of tools and their definitions (OpenAI-style function schemas). Requires X-API-Key. AgentBlit calls this endpoint when connecting or reconnecting to validate the key and refresh the tool catalog.

curl --location 'https://your-service.example.com/api/1.0/tools/list' \
  --header 'X-API-Key: apt_your_connector_api_key'

Response

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "list_entities",
        "description": "List all configured bookable entities for this agent.",
        "parameters": {
          "type": "object",
          "properties": {}
        }
      },
      "permission_mode": "always_allow"
    },
    {
      "type": "function",
      "function": {
        "name": "check_available_slots",
        "description": "Show available appointment times for one entity.",
        "parameters": {
          "type": "object",
          "properties": {
            "entity_id": {
              "type": "string",
              "description": "UUID of the entity to check"
            },
            "date_from": {
              "type": "string",
              "description": "Start date (YYYY-MM-DD) in the chat user's timezone"
            },
            "date_to": {
              "type": "string",
              "description": "End date (YYYY-MM-DD) in the chat user's timezone"
            },
            "timezone": {
              "type": "string",
              "description": "IANA timezone of the chat user (e.g. America/New_York)"
            }
          },
          "required": ["entity_id", "date_from", "date_to", "timezone"]
        }
      },
      "permission_mode": "always_allow",
      "_meta": {
        "ui": {
          "resourceUri": "ui://appointment/check-slots"
        }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "book_appointment",
        "description": "Book an appointment slot for a configured entity.",
        "parameters": {
          "type": "object",
          "properties": {
            "entity_id": { "type": "string" },
            "slot_start": {
              "type": "string",
              "description": "Slot start as ISO 8601 with offset"
            },
            "slot_end": {
              "type": "string",
              "description": "Slot end as ISO 8601 with offset"
            },
            "name": { "type": "string" },
            "email": { "type": "string" },
            "timezone": { "type": "string" }
          },
          "required": [
            "entity_id",
            "slot_start",
            "slot_end",
            "name",
            "email",
            "timezone"
          ]
        }
      },
      "permission_mode": "needs_approval"
    }
  ]
}

Each entry in tools must include:

type: "function"
function.name: Unique tool name used when calling the tool
function.description: What the tool does (shown to the model)
function.parameters: JSON Schema for the tool’s arguments

Optional fields:

Field	Description
`permission_mode`	`always_allow` (default), `needs_approval` (user must confirm), or `blocked`
`_meta.ui.resourceUri`	`ui://…` URI served by `/api/1.0/resources/read`
`_meta.ui.visibility`	`["model","app"]` (default), `["model"]`, or `["app"]`

2. Call tools

POST /api/1.0/tools/call

Executes one or more tool calls and returns results keyed by tool_call_id.

Request

curl --location 'https://your-service.example.com/api/1.0/tools/call' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: apt_your_connector_api_key' \
  --data '{
    "tool_calls": [
      {
        "id": "call_IWHXuqijtAyAj30UBMSfjlGU",
        "type": "function",
        "function": {
          "name": "check_available_slots",
          "arguments": "{\"entity_id\":\"22222222-2222-2222-2222-222222222222\",\"date_from\":\"2026-07-26\",\"date_to\":\"2026-07-28\",\"timezone\":\"America/New_York\"}"
        }
      }
    ]
  }'

Field	Description
`tool_calls`	Array of tool invocations from the agent
`tool_calls[].id`	Correlates with `tool_call_id` in the response
`tool_calls[].function.name`	Must match a name from `/tools/list`
`tool_calls[].function.arguments`	JSON string of arguments matching the tool’s parameter schema
`elicitation_result`	Optional; present when AgentBlit retries after `elicitation_required`

Success response

{
  "results": [
    {
      "tool_call_id": "call_IWHXuqijtAyAj30UBMSfjlGU",
      "result": {
        "content": [
          {
            "type": "text",
            "text": "{\"ok\":true,\"entity_id\":\"22222222-2222-2222-2222-222222222222\",\"slots\":[{\"start\":\"2026-07-26T14:00:00-04:00\",\"end\":\"2026-07-26T14:30:00-04:00\"}]}"
          }
        ]
      }
    }
  ]
}

Each item in results may include one of:

Field	Description
`result.content`	Array of `{ type: "text", text }` blocks; put JSON payloads in `text` as a string
`result.structuredContent`	Alternative opaque JSON result
`error`	Soft failure for this row (still HTTP 200)
`elicitation_required`	Ask the user for input; AgentBlit retries with `elicitation_result`

Return HTTP 400 for invalid bodies and 401 when the API key is missing or invalid. Prefer error on a result row for tool-level failures so other calls in the batch can still succeed.

3. UI resources (optional)

If a tool declares _meta.ui.resourceUri, implement:

GET /api/1.0/resources/read?uri=…

Requires X-API-Key.

curl --location 'https://your-service.example.com/api/1.0/resources/read?uri=ui%3A%2F%2Fappointment%2Fcheck-slots' \
  --header 'X-API-Key: apt_your_connector_api_key'

Response

{
  "contents": [
    {
      "uri": "ui://appointment/check-slots",
      "mimeType": "text/html;profile=mcp-app",
      "text": "<!DOCTYPE html>…",
      "_meta": {
        "ui": {
          "prefersBorder": true,
          "csp": {
            "connectDomains": [],
            "resourceDomains": []
          }
        }
      }
    }
  ]
}

Requirements:

uri must start with ui://
mimeType must be exactly text/html;profile=mcp-app
text is the full HTML document rendered in an iframe

The HTML should use the MCP Apps bridge (postMessage JSON-RPC) so the iframe can call tools through AgentBlit (tools/call) instead of calling your connector directly. Keep connectDomains empty unless the app must fetch external origins.

4. Deploy on a public URL

Host the endpoints on an HTTPS URL reachable from the internet (for example https://your-service.example.com). AgentBlit will call:

GET https://your-service.example.com/api/1.0/tools/list
POST https://your-service.example.com/api/1.0/tools/call
and resources/read if your tools declare UI

When you add a custom HTTP connector, AgentBlit probes tools/list (without an API key) to confirm the URL is reachable — a 401 response is treated as success because the endpoint exists. Use the base URL of your deployment when registering (no path suffix). Optionally set a dashboard URL so users can open your UI (in a new tab) to mint an API key.

On connect or reconnect, AgentBlit calls tools/list with the pasted API key. If the key is invalid, connection fails.

Add a custom connector in AgentBlit

After your APIs are live:

Create an account in the AgentBlit console.
Create an agent for your use case.
Open Connectors → Add custom connector.
Choose Custom HTTP connector, enter your service’s public base URL, and optionally a dashboard URL.
On the agent page, click Add tool, select your connector, paste the API key from your dashboard, and connect. AgentBlit verifies the key via tools/list and stores the discovered tools.

AgentBlit discovers tools from your list endpoint and invokes them through the call endpoint when the agent needs them.

Custom HTTP Connector

TypeScript

Go

On this page