Agent Tools

Agents use three types of tools: API tools (HTTP endpoints), Database tools (SQL queries), and MCP tools (external MCP servers). All tools are resolved at runtime via the ToolRegistry.

Tool Types

Type	Schema	Description
api_config	HTTP tool	Calls external REST APIs
db_config	SQL tool	Executes parameterized SQL queries
MCP tools	MCP server	Tools from connected MCP servers

---

Database Connections

Database connections are managed through the /api/database-configs endpoints with secure credential storage via Vault.

Security Architecture

┌─────────────────────────────────────────────────┐
│            private_context_connections           │
├─────────────────────────────────────────────────┤
│  connection_config: {                           │
│    "supabase_url": "https://xxx.supabase.co"    │  ← NO KEY
│  }                                              │
│  vault_secret_id: "MY_SUPABASE_KEY"             │  ← REFERENCE
└─────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────┐
│              tenant_api_secrets                  │
├─────────────────────────────────────────────────┤
│  name: "MY_SUPABASE_KEY"                        │
│  encrypted_value: "iv:authTag:data"             │  ← AES-256-GCM
└─────────────────────────────────────────────────┘

Credential Security

Never store passwords or API keys directly in connection_config. Use the Vault Secrets system (tenant_api_secrets) for secure credential storage with AES-256-GCM encryption.

Supported Providers

Supabase:

Field	Location	Description
supabase_url	connection_config	Supabase project URL
supabase_anon_key	vault	Anon key (via vault_secret_id)

PostgreSQL:

Field	Location	Description
host	connection_config	Server hostname
port	connection_config	Port (default: 5432)
database	connection_config	Database name
username	connection_config	User
password	vault	Password (via vault_secret_id)
ssl	connection_config	Use SSL (boolean)

---

Connection Endpoints

Endpoint	Method	Auth	Description
GET /api/database-configs	GET	JWT / API Key	List connections
GET /api/database-configs/:id	GET	JWT / API Key	Get connection details
POST /api/database-configs	POST	JWT only	Create connection
PATCH /api/database-configs/:id	PATCH	JWT only	Update connection
DELETE /api/database-configs/:id	DELETE	JWT only	Soft delete
POST /api/database-configs/:id/restore	POST	JWT only	Restore deleted

Schema Cache

Endpoint	Method	Description
GET /api/database-configs/:id/schema	GET	Get cached schema
POST /api/database-configs/:id/refresh-schema	POST	Refresh schema (connects to DB)
GET /api/database-configs/:id/freshness	GET	Check if refresh is needed

Vault Integration

The refresh-schema endpoint automatically resolves vault credentials before connecting. No need to send credentials in the request.

Semantic Cache

Endpoint	Method	Description
GET /api/database-configs/:id/semantic	GET	Get semantic cache
POST /api/database-configs/:id/refresh-semantic	POST	Update semantic data
POST /api/database-configs/:id/enrich-semantic	POST	Auto-enrich from schema

---

Connection Testing

POST /api/db/test-connection (Recommended)

Unified endpoint for testing PostgreSQL and Supabase connections.

{
  "provider": "supabase",
  "connection_config": {
    "supabase_url": "https://xxx.supabase.co",
    "supabase_anon_key": "eyJ..."
  }
}

Response:

{
  "success": true,
  "latency_ms": 135,
  "provider": "supabase",
  "details": {
    "host_reachable": true,
    "auth_successful": true,
    "database_accessible": true
  }
}

---

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 tenant_api_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.

---

db_config Schema Contract

The db_config schema defines SQL query tools. Required fields in schema_data:

Field	Required	Description
connection_id	Yes	UUID referencing private_context_connections
tool_definition	Yes	Tool name, description, and input_schema
query_template	Yes	SQL with $1, $2 parameters
parameter_mapping	Yes	Array mapping input fields to $N positions
result_mapping	No	Format (raw/table/summary), max_rows (default: 100)

---

Authentication Summary

Database Connections

Endpoint	Method	JWT	API Key
GET /api/database-configs	GET	Yes	Yes
GET /api/database-configs/:id	GET	Yes	Yes
GET /api/database-configs/:id/schema	GET	Yes	Yes
GET /api/database-configs/:id/semantic	GET	Yes	Yes
POST /api/database-configs	POST	Yes	No
PATCH /api/database-configs/:id	PATCH	Yes	No
DELETE /api/database-configs/:id	DELETE	Yes	No
POST /api/database-configs/:id/refresh-schema	POST	Yes	No
POST /api/db/test-connection	POST	Yes	No

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