Tools API

Manage MCP tool configurations.

List Tools

Returns all available MCP tools.

GET /v1/tool

Query Parameters:

Parameter	Type	Description
`user_only`	boolean	Return only user-created tools (default: false)

Response:

{
  "tools": [
    {
      "identifier": "database",
      "version": "1.0.0",
      "name": "Database Tool",
      "description": "SQLite database access",
      "provider": "Archia",
      "icon": null,
      "tool_type": "mcp",
      "local": {
        "cmd": "mcp-sqlite",
        "args": ["--database", "/data/db.sqlite"],
        "env": {},
        "timeout_secs": 30
      },
      "remote": null
    }
  ]
}

Get Tool

Returns a specific tool by identifier.

GET /v1/tool/{identifier}

Path Parameters:

Parameter	Type	Description
`identifier`	string	Tool identifier (e.g., `org/tool` or `my-tool`)

Response: Single tool object.

Example:

curl http://localhost:8080/v1/tool/database

Create Tool

Creates a new tool configuration.

POST /v1/tool

Local Tool

For tools running locally via STDIO:

Request Body:

{
  "identifier": "my-tool",
  "name": "My Tool",
  "description": "A custom MCP tool",
  "version": "1.0.0",
  "provider": "My Organization",
  "local": {
    "cmd": "my-mcp-server",
    "args": ["--config", "/path/to/config"],
    "env": {"API_KEY": "secret"},
    "timeout_secs": 30
  }
}

Remote Tool

For tools connecting to external MCP servers:

Request Body:

{
  "identifier": "remote-tool",
  "name": "Remote Tool",
  "description": "External MCP service",
  "remote": {
    "url": "https://api.example.com/mcp",
    "transport": "streaming_http",
    "auth_type": "bearer",
    "auth_token": "your-token",
    "timeout_secs": 60
  }
}

Parameters

Field	Type	Required	Description
`identifier`	string	Yes	Unique tool identifier
`name`	string	Yes	Human-readable display name
`description`	string	No	Description of the tool’s purpose
`version`	string	No	Semantic version (default: “0.0.0”)
`provider`	string	No	Organization or author name
`icon`	string	No	URL or path to tool icon
`local`	object	No*	Local tool configuration
`remote`	object	No*	Remote tool configuration

*Either local or remote must be provided.

Local Configuration

Field	Type	Required	Description
`cmd`	string	Yes	Executable command or path
`args`	array	No	Command-line arguments
`env`	object	No	Environment variables
`timeout_secs`	integer	No	Tool call timeout (default: 30)

Remote Configuration

Field	Type	Required	Description
`url`	string	Yes	MCP server URL
`transport`	string	Yes	“streaming_http” or “sse”
`auth_type`	string	No	“none”, “bearer”, or “oauth”
`auth_token`	string	No	Bearer token (when auth_type is “bearer”)
`oauth_scopes`	array	No	OAuth scopes to request
`oauth_client_id`	string	No	OAuth client ID
`oauth_client_secret`	string	No	OAuth client secret
`timeout_secs`	integer	No	Tool call timeout (default: 30)

Response: 201 Created with the created tool.

Update Tool

Updates an existing tool configuration.

PUT /v1/tool/{identifier}

Path Parameters:

Parameter	Type	Description
`identifier`	string	Tool identifier to update

Request Body: Same fields as create, all optional.

Response: 200 OK with the updated tool.

Example:

curl -X PUT http://localhost:8080/v1/tool/my-tool \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description",
    "local": {
      "cmd": "my-mcp-server",
      "args": ["--config", "/new/path"],
      "timeout_secs": 60
    }
  }'

Delete Tool

Deletes a tool configuration.

DELETE /v1/tool/{identifier}

Path Parameters:

Parameter	Type	Description
`identifier`	string	Tool identifier to delete

Response: 204 No Content

Example:

curl -X DELETE http://localhost:8080/v1/tool/my-tool

Examples

Create a Database Tool

curl -X POST http://localhost:8080/v1/tool \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "sqlite-db",
    "name": "SQLite Database",
    "description": "Query SQLite databases",
    "local": {
      "cmd": "mcp-sqlite",
      "args": ["--database", "/data/analytics.db"],
      "timeout_secs": 30
    }
  }'

Create a GitHub Tool

curl -X POST http://localhost:8080/v1/tool \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "github",
    "name": "GitHub Integration",
    "description": "Interact with GitHub repositories",
    "local": {
      "cmd": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github@latest"],
      "env": {"GITHUB_TOKEN": "ghp_xxxxxxxxxxxx"},
      "timeout_secs": 60
    }
  }'

Create a Remote API Tool

curl -X POST http://localhost:8080/v1/tool \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "cloud-service",
    "name": "Cloud Service API",
    "description": "Access cloud-hosted service",
    "remote": {
      "url": "https://api.cloudservice.com/mcp",
      "transport": "streaming_http",
      "auth_type": "bearer",
      "auth_token": "your-api-key",
      "timeout_secs": 120
    }
  }'

List Only User Tools

curl "http://localhost:8080/v1/tool?user_only=true"

Granting Tool Access to Agents

After creating tools, grant agents access via the agent configuration:

curl -X PUT http://localhost:8080/v1/agent/config/assistant \
  -H "Content-Type: application/json" \
  -d '{
    "mcp_tools": {
      "sqlite-db": ["query", "list_tables"],
      "github": null
    }
  }'

null or [] grants access to all tools from that MCP
An array of strings grants access to only those specific tools

Next Steps

Responses API → - Use tools via agent routing
Agents API → - Grant tool access to agents
Tool Configuration → - File-based tool configuration

Keyboard shortcuts

Archia.io