Tools API — Configurator

The Tools API manages the lifecycle of API, database, and custom tools: creation, versioned configuration, and deployment to MCP. For architecture and configuration, see Configurator.

Paths are relative to the Configurator service root (port 8100 locally). Authentication, required headers, errors, and the pagination envelope follow the API conventions; see Pagination for page and page_size.

Tool Types

Every route except bulk-fetch and mcp-list requires a type: in the JSON body for POST and PUT, and as a query parameter otherwise. A missing type returns 400.

Endpoints

There is no PATCH, versions, or test route.

Create or Update a Tool

POST /api/v1/tools/ and PUT /api/v1/tools/{id}/

Fields on every configuration: requires_approval (default false) and read-only version, status, and mcp_tool_name.

API tool configuration

DB tool configuration

For engine: files, Configurator processes the files asynchronously and reports processing_status (pending, processing, ready, failed), processing_error, processed_at, and the generated data_dictionary. A draft cannot be updated while processing runs, and cannot be deployed until it is ready.

Custom tool configuration

Secret values are masked in responses unless the caller is a superuser or may manage custom tools.

curl -s -X POST 'http://localhost:8100/api/v1/tools/' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'X-Org-Id: YOUR_ORG_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "api",
    "name": "weather_lookup",
    "description": "Current weather for a city",
    "configuration": {
      "url": "https://api.weather.example.com/v1/current",
      "method": "get",
      "input_schema": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  }'

The response is the tool (id, org_id, name, description, functions, type, timestamps) with a configurations list, newest version first.

Versioning

Versions are major.minor strings and start at 1.0.

New and updated configurations emit <prefix>.configuration.added or <prefix>.configuration.updated on the configurator Kafka topic, where the prefix is api_tool, db_tool, or custom_tool.

MCP tool name

Each configuration gets an mcp_tool_name of the form {org}-{type}-{name}-{major}_{minor}, with the organization name and tool name lowercased and non-alphanumeric characters replaced by _. For example, acme_corp-api-weather_lookup-1_0. MCP uses this name to list and call the tool.

List Tools

GET /api/v1/tools/?type=api

Get a Tool

GET /api/v1/tools/{id}/?type=api accepts status and version to filter the returned configurations.

Deploy

POST /api/v1/tools/{id}/deploy/ with body {"type": "api"}

Deploys the latest draft. Returns 400 with No draft configuration exists to deploy., The configuration is already deployed., or, for file-based DB tools, Cannot deploy: file processing not complete.. Consumers receive <prefix>.configuration.deployed, and MCP syncs the tool into its cache.

Delete

DELETE /api/v1/tools/{id}/?type=api soft-deletes the tool and returns 204. Consumers receive <prefix>.deleted.

Bulk Fetch

GET /api/v1/tools/bulk-fetch/?tool=api:<uuid>:1.0&tool=custom:<uuid>:2.1

Each tool value is a type:uuid:version triplet, and types can be mixed. The response is a list in request order with the exact requested version, whether draft or deployed. Items whose tool or version does not exist are omitted.

MCP List

GET /api/v1/tools/mcp-list/?query_json=[{"type":"api","mcp_tool_names":["..."]}]

Used by the MCP service to resolve deployed tools by name. query_json accepts up to three {type, mcp_tool_names} items. Requires X-Org-Id. With include_diagnostics=true, the response is {tools, projection, errors} instead of a list. Response headers X-Configurator-Projection-State, X-Configurator-Projection-Deployment-State, X-Configurator-Projection-Refresh-Required, X-Configurator-Projection-Resolved-Count, and X-Configurator-Projection-Error-Count summarize the resolution.

Related APIs

• Agents API: agents that use tools
• Apps API: apps that expose agents
• MCP Tools API: tool listing and execution on MCP