List Tools

Retrieve tools including local tools, OpenAPI servers, and MCP servers

GET /api/tools

List Tools

cURL

curl --request GET \
  --url https://api.example.com/api/tools/

200

{
  "tools": [
    {
      "id": "<string>",
      "user_id": "<string>",
      "name": "<string>",
      "meta": {},
      "access_grants": [
        {
          "principal_type": "<string>",
          "principal_id": "<string>",
          "permission": "<string>"
        }
      ],
      "write_access": true,
      "updated_at": 123,
      "created_at": 123
    }
  ]
}

Get Tools

GET

curl -X GET "https://your-instance.com/api/tools/" \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns all available tools including:

• Local tools (Python-based tools stored in the database)
• OpenAPI tool servers
• MCP (Model Context Protocol) tool servers

Response

tools · array

Array of tool objects

Show ToolUserResponse properties

id · string · required

Unique identifier for the tool. Server tools use format server:{id} or server:mcp:{id}

user_id · string · required

ID of the user who created the tool (for local tools) or server ID (for server tools)

name · string · required

Display name of the tool

meta · object · required

Tool metadata

Show meta properties

description · string

Tool description

manifest · object

Tool manifest data

has_user_valves · boolean

Whether the tool has user-configurable valves (local tools only)

authenticated · boolean

OAuth authentication status (MCP servers with OAuth 2.1 only)

updated_at · integer · required

Unix timestamp of last update

created_at · integer · required

Unix timestamp of creation

Access Control

• Admin users (with BYPASS_ADMIN_ACCESS_CONTROL): See all tools
• Regular users: See only:
  • Tools they created
  • Tools with read access grants
  • Server tools with appropriate access grants

Get Tool List

GET /api/tools/list

curl -X GET "https://your-instance.com/api/tools/list" \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns a list of local tools with access information.

Response

tools · array

Array of tool objects with access information

Show ToolAccessResponse properties

id · string · required

Tool identifier

user_id · string · required

Creator user ID

name · string · required

Tool name

meta · object · required

Tool metadata

access_grants · array · required

Access grant configurations

Show access grant properties

principal_type · string

Type of principal: “user” or “group”

principal_id · string

User ID, group ID, or ”*” for all users

permission · string

Permission level: “read” or “write”

write_access · boolean · required

Whether the current user has write access to this tool

updated_at · integer · required

Last update timestamp

created_at · integer · required

Creation timestamp

Access Determination

Write access is granted if:

• User is an admin (with BYPASS_ADMIN_ACCESS_CONTROL)
• User is the tool creator
• User has a write permission grant
• User is in a group with write permission grant

Export Tools

GET /api/tools/export

curl -X GET "https://your-instance.com/api/tools/export" \
  -H "Authorization: Bearer YOUR_API_KEY"

Export all tools accessible to the user. Requires workspace.tools_export permission for non-admin users.

Response

Returns an array of complete ToolModel objects including:

• Tool ID, name, and metadata
• Full source code content
• Tool specifications
• Access grants

Permissions

• Admin users (with BYPASS_ADMIN_ACCESS_CONTROL): Export all tools
• Non-admin users: Requires workspace.tools_export permission, exports only tools with read access

Tool Types

Local Tools

Python-based tools stored in the database:

• Identified by simple string IDs (e.g., "calculator")
• Created and managed through the API
• Support user valves for customization

OpenAPI Tool Servers

External OpenAPI-compliant tool servers:

• ID format: server:{id}
• Configured in TOOL_SERVER_CONNECTIONS
• Access controlled via server configuration

MCP Tool Servers

Model Context Protocol servers:

• ID format: server:mcp:{id}
• Support OAuth 2.1 authentication
• Access controlled via server configuration
• Return authenticated field for OAuth status

Authentication

All endpoints require verified user authentication. Some operations require admin privileges or specific permissions.