Skip to content
Starfly

Register a tool (any protocol)

POST
/v1/tools
 
curl --request POST \
  --url http://localhost:8693/v1/tools \
  --header 'Content-Type: application/json' \
  --data '{ "tool_id": "example", "name": "example", "resource_uri": "example", "required_capabilities": [ "example" ], "max_blast_radius": "example", "requires_execution": true, "allowed_operations": [ "example" ], "allowed_targets": [ "example" ] }'

Register a tool with its security requirements and supported protocols. If protocols is omitted or empty, the tool defaults to ["mcp"] for backwards compatibility.

Request Body required

Section titled “Request Body required ”
Media type application/json

Tool registration entry for the universal tool-call layer (ADR-0022 / UTC-008). Extends ToolEntry with protocol declarations and adapter metadata. Backwards-compatible: omitting protocols defaults to ["mcp"].

object
protocols

Protocols this tool accepts. Verifier rejects calls arriving via an unlisted protocol. Supported values: “mcp”, “http”, “a2a/2025-draft-01”. Omit to default to [“mcp”].

Array<string>
Example 
[
  "mcp",
  "http"
]
description

Human-readable tool description (shown in tool listings)

string
version

Tool schema version (semver)

string
tool_id
required

Unique identifier for the tool

string
name
required

Human-readable name

string
resource_uri

RFC 8707 resource indicator. Token aud must match this.

string
required_capabilities

Capabilities the token must include

Array<string>
max_blast_radius

Maximum blast radius scope (e.g., “namespace:analytics”)

string
requires_execution

Whether execution binding checks (exec_act, inp_hash, target) are enforced

boolean
allowed_operations

Valid exec_act values (when requires_execution is true)

Array<string>
allowed_targets

Valid target URIs (when requires_execution is true)

Array<string>

Responses

Section titled “ Responses ”

201

Section titled “201 ”

Tool registered

400

Section titled “400 ”

Invalid request

Media type application/json
object
error
required

Error code (RFC 8693 compatible)

string
Allowed values: invalid_request unsupported_grant_type access_denied server_error not_implemented not_found method_not_allowed
error_description

Human-readable error detail

string
Example 
{
  "error": "invalid_request"
}

503

Section titled “503 ”

Tool registry not initialised