Agent Tools

Agents use two types of tools: API tools (HTTP endpoints) and MCP tools (external MCP servers). All tools are resolved at runtime by the platform's tool resolution engine.

Tool Types

Type	Schema	Description
api_config	HTTP tool	Calls external REST APIs
MCP tools	MCP server	Tools from connected MCP servers

---

Database tools were removed

The tenant database feature — database connections (/api/database-configs, /api/db/*), the db_config schema type and the db_event trigger — was removed on 2026-10-03. The server now rejects db_config schemas. To give an agent access to a database, expose the data through an HTTP API and add it as an api_config tool, or connect an MCP server you control (for PostgreSQL, see the MCP Bridge).

---

MCP Tools

MCP (Model Context Protocol) tools connect agents to external business systems like ERPs, CRMs, and proprietary APIs. Each agent can have up to 10 MCP servers configured.

How It Works

1. Configure an MCP server for your agent via the REST API or MCP Builder tools
2. The platform connects to the server, loads available tools, and caches them for 5 minutes
3. Tools are automatically prefixed with the server name to avoid naming collisions (e.g., erp_listar_pedidos)
4. Authentication is resolved securely via Vault (Bearer token or API Key)

Supported Transports

Transport	Use Case
http	Recommended. Streamable HTTP with automatic SSE fallback
sse	Legacy SSE-only servers
stdio	Local servers via stdin/stdout

Reliability Features

Feature	Description
Auto-recovery	Servers that go down are automatically retried on the next agent request. If reconnection succeeds, status returns to active
Health check	Periodic checks every 60s detect degraded servers and update their status
Tool call timeout	Each MCP tool call has a 30-second timeout to prevent indefinite blocking
Connection timeout	Initial connection to an MCP server times out after 10 seconds
Graceful shutdown	All MCP connections are properly closed during server shutdown

MCP Server Status

Status	Behavior
active	Normal operation — tools are loaded
error	Server had a failure — platform will attempt auto-recovery on next request
inactive	Disabled — tools are not loaded

Auto-Recovery

You don't need to manually restart MCP servers that encounter transient errors. The platform automatically retries connection on the next agent request and restores the server to active status upon success.

MCP Server Endpoints

Full CRUD for managing MCP servers linked to agents.

Endpoint	Method	Auth	Description
GET /api/mcp-servers	GET	JWT / API Key	List MCP servers (optional filters: agent_id, status)
GET /api/mcp-servers/:id	GET	JWT / API Key	Get MCP server details (includes config)
POST /api/mcp-servers	POST	JWT only	Register a new MCP server for an agent
PATCH /api/mcp-servers/:id	PATCH	JWT only	Update MCP server configuration
DELETE /api/mcp-servers/:id	DELETE	JWT only	Remove MCP server (hard delete)
POST /api/mcp-servers/:id/invalidate-cache	POST	JWT only	Invalidate tool cache for a specific server
POST /api/mcp-servers/invalidate-cache	POST	JWT only	Invalidate tool cache for ALL servers in the tenant

Create / Update fields:

Field	Required	Type	Description
agent_id	Create only	UUID	Agent to link the server to
name	Create only	string	Server display name
endpoint	Create only	string	Server URL or stdio command
description	No	string	Optional description
transport	No	http | sse | stdio	Transport type (default: http)
auth_method	No	none | bearer | api_key | oauth	Auth method (default: none)
config	No	object	Additional config (vault_secret_id, headers, timeout, defaults_from_context)
status	Update only	active | inactive	Server status

Cache Invalidation

After updating tools on your external MCP server, call the invalidate-cache endpoint to force the platform to reload the tool list immediately instead of waiting for the 5-minute cache TTL.

---

api_config Authentication

API tools support authenticated requests to external APIs. The auth configuration uses prefix as the canonical field:

Field	Required	Description
prefix	Yes*	Auth prefix: "Bearer", "Basic", or "" (for API key)
secret_ref	Recommended	Reference to encrypted secret in Vault Secrets
type	Deprecated	Legacy field — use prefix instead. If only type is provided, it is automatically inferred to prefix

Example:

{
  "editor_schema": {
    "api": {
      "base_url": "https://api.example.com",
      "auth": {
        "prefix": "Bearer",
        "secret_ref": "MY_API_TOKEN"
      },
      "endpoints": [{ "name": "list_items", "method": "GET", "path": "/items" }]
    }
  }
}

auth.type is Deprecated

The auth.type field is deprecated in a previous release. If provided without prefix, the runtime infers: bearer → Bearer, basic → Basic, api_key → "". A deprecation warning will appear in validation results. Migrate to auth.prefix for clarity.

---

Authentication Summary

MCP Servers

Endpoint	Method	JWT	API Key
GET /api/mcp-servers	GET	Yes	Yes
GET /api/mcp-servers/:id	GET	Yes	Yes
POST /api/mcp-servers	POST	Yes	No
PATCH /api/mcp-servers/:id	PATCH	Yes	No
DELETE /api/mcp-servers/:id	DELETE	Yes	No
POST /api/mcp-servers/:id/invalidate-cache	POST	Yes	No
POST /api/mcp-servers/invalidate-cache	POST	Yes	No