Skip to main content

​
Quickstart Guide

This guide will get you from zero to executing your first LLM tool in minutes.

​
Prerequisites

Before you begin, ensure you have:

Java 21 LTS

Download from Adoptium or Oracle

Maven 3.8+

Included via mvnw wrapper — no separate installation needed
Optional: GraalVM 21 for native compilation (sub-second startup). Not required for getting started.

​
Installation

1

Clone the Repository

git clone https://github.com/Vrivaans/handsaiv3.git
cd handsaiv3
2

Start HandsAI

Run the service using the Maven wrapper:
./mvnw spring-boot:run
The service will start on http://localhost:8080. You’ll see:
Initializing tool cache
Tool cache initialized with 0 tools
Started Handsai in 2.341 seconds (process running for 2.789)
The database file handsai.db is created automatically in the project root. No setup needed.
3

Access the UI

Open your browser to http://localhost:8080You’ll see the HandsAI admin panel with:
  • Active tools list (empty on first run)
  • Import/Export tools
  • Analytics dashboard

​
Register Your First API Tool

Let’s register a real weather API so your LLM can check the weather anywhere in the world.
1

Get a WeatherAPI Key

  1. Sign up at weatherapi.com (free tier available)
  2. Copy your API key from the dashboard
2

Import the Weather Tool

Navigate to the import section in the UI or use the API directly:
curl -X POST http://localhost:8080/api/import/providers \
  -H "Content-Type: application/json" \
  -d '[
    {
      "name": "Weather API",
      "code": "weather",
      "baseUrl": "https://api.weatherapi.com",
      "authenticationType": "API_KEY",
      "apiKeyLocation": "QUERY_PARAMETER",
      "apiKeyName": "key",
      "apiKeyValue": "YOUR_API_KEY_HERE",
      "tools": [
        {
          "name": "Get Current Weather",
          "code": "api-clima",
          "description": "Get current weather for a specific city",
          "endpointPath": "/v1/current.json",
          "httpMethod": "GET",
          "parameters": [
            {
              "name": "q",
              "type": "STRING",
              "description": "City name (e.g., 'London', 'New York')",
              "required": true
            }
          ]
        }
      ]
    }
  ]'
Replace YOUR_API_KEY_HERE with your actual WeatherAPI key. The value is automatically encrypted in the database.
3

Verify Tool Registration

Check that the tool is discoverable via MCP:
curl http://localhost:8080/mcp/tools/list
You should see:
{
  "jsonrpc": "2.0",
  "result": {
    "tools": [
      {
        "name": "Get Current Weather",
        "description": "Get current weather for a specific city",
        "inputSchema": {
          "type": "object",
          "properties": {
            "q": {
              "type": "string",
              "description": "City name (e.g., 'London', 'New York')"
            }
          },
          "required": ["q"]
        }
      }
    ]
  }
}

​
Set Up HandsAI Bridge for MCP

To connect HandsAI to your LLM client (Claude Desktop, Antigravity, VS Code, etc.), you need the HandsAI Bridge.
1

Install HandsAI Bridge

Clone and build the bridge:
git clone https://github.com/Vrivaans/handsai-bridge.git
cd handsai-bridge
go build -o handsai-mcp main.go
This creates a binary called handsai-mcp.
2

Configure Your MCP Client

Add the bridge to your MCP client configuration:
{
  "mcpServers": {
    "handsai": {
      "command": "/absolute/path/to/handsai-mcp",
      "args": ["mcp"]
    }
  }
}
Use the absolute path to the handsai-mcp binary. Relative paths may not work depending on your client.
3

Restart Your MCP Client

Restart Claude Desktop, Antigravity, or your IDE with MCP support.The client will detect HandsAI as an available MCP server and load all registered tools.

​
Execute Your First Tool

Now test the integration end-to-end.
Ask your LLM:
“What’s the weather in Buenos Aires?”
The LLM will:
  1. Discover the Get Current Weather tool via MCP
  2. Call the tool with {"q": "Buenos Aires"}
  3. HandsAI executes the API call to WeatherAPI
  4. Return the JSON response to the LLM
  5. The LLM formats the weather data in natural language
Example Response:
“The current weather in Buenos Aires is 15°C (59°F) with partly cloudy skies. Wind is 10 km/h from the east.”

​
Next Steps

Import More APIs

Check out the pre-built use cases:
  • Email sending (Resend)
  • Social media posting (Ayrshare)
  • AI search (Tavily)
  • GitHub automation
Import them from docs/casos-de-uso/NUEVOS_HITOS.json

Explore the Architecture

Learn how HandsAI’s caching, authentication, and execution flow works under the hood.

API Reference

Complete documentation of all admin and MCP endpoints.

Native Compilation

Compile to native executable for < 1.5s startup:
./mvnw -Pnative native:compile
./target/hands-ai-v2

​
Troubleshooting

  1. Verify the tool is registered: curl http://localhost:8080/mcp/tools/list
  2. Check that HandsAI is running on port 8080
  3. Ensure the bridge configuration uses the correct absolute path
  4. Restart your MCP client after configuration changes
  • Check that your API key is correct
  • Verify apiKeyLocation matches the API’s requirements (HEADER, QUERY_PARAMETER, or IN_BODY)
  • For OAuth2, ensure isDynamicAuth is enabled with correct token endpoint
Change the port in application.properties:
server.port=8081
Update the bridge config.json to point to the new port.
Join the community or report issues at github.com/Vrivaans/handsaiv3

Build docs developers (and LLMs) love

Get started for freeTalk to us