Skip to main content

​
HandsAI - AI as the brain, HandsAI as its hands

HandsAI is the bridge between LLMs and the real world. The concept is simple:

The Core Idea

Register any REST API → HandsAI exposes it as an MCP tool → Your LLM can use it.No code. No plugins. No complex configuration. Just register the endpoint, its parameters, and HandsAI does the rest: the LLM discovers available tools, calls them when needed, and receives results — all through the standard MCP protocol.

​
Architecture Overview

HandsAI provides a complete bridge architecture connecting LLMs to external APIs: 
[Your LLM / Claude / Any MCP Client]
         ↓  MCP (JSON-RPC / stdio)
  [HandsAI Bridge (Go)]
         ↓  HTTP REST
     [HandsAI v3 (Spring Boot)]
         ↓  HTTP REST
 [Any External API You Register]
The HandsAI Bridge is a separate Go binary that translates MCP’s stdio protocol to HTTP REST calls. See the HandsAI Bridge repository for installation.

​
Key Features

Dynamic Tool Discovery

LLMs discover available tools at runtime through the MCP protocol. Tools are cached in memory for high performance.

Zero-Code Registration

Register APIs from the UI or import via JSON. No code changes needed — tools are available immediately.

Flexible Authentication

Supports OAuth2, API Keys (header/query/body), Bearer tokens, and dynamic token refresh with automatic retry on expiration.

GraalVM Native

Compiles to native executable with < 1.5s startup time and low memory footprint using GraalVM AOT compilation.

Virtual Threads

Leverages Java 21 Virtual Threads for high concurrency and scalability without the overhead of traditional threads.

SQLite Powered

Zero-configuration embedded database with WAL mode for high-concurrency operations and batch processing.

Smart Caching

Tool definitions cached in-memory (ToolCacheManager) for instant discovery and reduced database hits.

Rich Parameter Types

Full support for STRING, NUMBER, BOOLEAN, and ARRAY types with automatic JSON deserialization.

​
How It Works in Practice

1

Start HandsAI

Launch the service with ./mvnw spring-boot:run — runs on http://localhost:8080
2

Register an API

Import tools via the UI or JSON. Tools are immediately available — no restarts needed.
3

MCP Client Discovers

Your MCP client (Claude Desktop, Antigravity, VS Code) sees the tool automatically.
4

Execute in Real-Time

The LLM calls the tool, HandsAI executes the API request, and returns results instantly.

​
Real-World Use Cases

Register WeatherAPI to let your LLM fetch current weather for any city.Example: “What’s the weather in Buenos Aires?” → LLM calls api-clima tool → Returns real-time weather data.See the Weather API Use Case for complete setup.
Post to LinkedIn, Twitter, Instagram, and more from your LLM using Ayrshare’s API.Example: Agent posts to LinkedIn directly from the IDE without opening a browser. Supports ARRAY parameters for multi-platform posting.Live example on LinkedIn
Send emails through Resend API with HTML content, custom headers, and verified domains.Registered as a BEARER_TOKEN provider with parameters for from, to, subject, and html body.
Integrate Tavily’s AI search for precise answers and sources.Uses IN_BODY API key authentication with configurable search depth and image inclusion.
Create issues, list pull requests, and manage repositories directly from your LLM.Demonstrates path parameters (/repos/{owner}/{repo}/issues) and dynamic URL building.
Delegate coding tasks to Google’s Jules agent. Create sessions, monitor progress, approve plans — Jules opens PRs automatically.Uses advanced features like bodyPayloadTemplate for structured JSON payloads with parameter interpolation.

Quickstart

Get HandsAI running in minutes

Architecture

Deep dive into system design

API Reference

Complete endpoint documentation

​
Technology Stack

Spring Boot 3.5.4

Modern Java web framework with Spring MVC for REST APIs

Java 21 LTS

Latest LTS with Virtual Threads, Records, Pattern Matching

GraalVM Native Image

AOT compilation for sub-second startup times

SQLite + JPA

Embedded database with Hibernate and custom dialect

​
Open Source

HandsAI is open source under the AGPL-3.0 license.
Ready to get started? Head to the Quickstart Guide to register your first API tool in under 5 minutes.

Build docs developers (and LLMs) love

Get started for freeTalk to us