Skip to main content
The HandsAI Bridge is a lightweight Go binary that translates the Model Context Protocol (MCP) stdio communication to HTTP REST calls. This allows MCP clients like Claude Desktop, Antigravity, and VS Code to seamlessly discover and execute tools registered in HandsAI.

​
What the Bridge Does

The bridge acts as a protocol adapter: 
[MCP Client (Claude Desktop, VS Code, etc.)]
         ↓  MCP over stdio (JSON-RPC)
      [HandsAI Bridge (Go)]
         ↓  HTTP REST
   [HandsAI Server (Spring Boot)]
         ↓  HTTP REST
  [External APIs you registered]
  • Input: JSON-RPC messages over stdio from MCP clients
  • Output: HTTP REST calls to HandsAI server at http://localhost:8080
  • Benefits: Zero configuration for clients, single integration point

​
Prerequisites

1

HandsAI Server Running

Ensure HandsAI is running on http://localhost:8080:
cd handsaiv3
./mvnw spring-boot:run
2

Go Installed (for building from source)

If building from source, install Go 1.21 or later:
go version
Download from golang.org if needed.

​
Installation

Download the pre-built binary from the releases page:
# Download latest release
curl -L -o handsai-mcp https://github.com/Vrivaans/handsai-bridge/releases/latest/download/handsai-mcp-linux

# Make executable
chmod +x handsai-mcp

# Move to a permanent location
sudo mv handsai-mcp /usr/local/bin/
Replace handsai-mcp-linux with handsai-mcp-macos or handsai-mcp-windows.exe based on your platform.

​
Configuration for MCP Clients

​
Claude Desktop

Add HandsAI to your Claude Desktop configuration:
1

Locate Configuration File

Find your Claude Desktop config file:
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json
2

Edit Configuration

Add the HandsAI bridge to the mcpServers section:
claude_desktop_config.json
{
  "mcpServers": {
    "handsai": {
      "command": "/usr/local/bin/handsai-mcp",
      "args": ["mcp"]
    }
  }
}
Use the absolute path to the handsai-mcp binary. Relative paths and ~ may not work.
3

Restart Claude Desktop

Quit and restart Claude Desktop completely for changes to take effect.
4

Verify Connection

In Claude Desktop, you should see HandsAI tools available:Claude Desktop detecting HandsAI tools

​
Antigravity (VS Code Extension)

Configure HandsAI in Antigravity’s MCP settings:
1

Open MCP Configuration

In VS Code, find the Antigravity MCP configuration file:
  • macOS/Linux: ~/.config/antigravity/mcp_config.json
  • Windows: %APPDATA%\antigravity\mcp_config.json
2

Add HandsAI Server

mcp_config.json
{
  "mcpServers": {
    "handsai": {
      "command": "/usr/local/bin/handsai-mcp",
      "args": ["mcp"]
    }
  }
}
3

Reload VS Code

Reload the VS Code window or restart Antigravity.
4

Verify Tools

Antigravity should now display all tools registered in HandsAI:Antigravity detecting HandsAI tools

​
Generic MCP Client

For any MCP-compatible client: 
{
  "mcpServers": {
    "handsai": {
      "command": "/absolute/path/to/handsai-mcp",
      "args": ["mcp"]
    }
  }
}

​
Advanced Configuration

​
Custom HandsAI Server URL

If HandsAI is running on a different host or port, create a config.json file in the same directory as handsai-mcp:
config.json
{
  "handsai_url": "http://192.168.1.100:8080"
}
The bridge will automatically detect and use this configuration.

​
Environment Variables

Alternatively, set the HandsAI URL via environment variable: 
export HANDSAI_URL="http://192.168.1.100:8080"
/usr/local/bin/handsai-mcp mcp

​
Testing the Connection

1

Start HandsAI Server

cd handsaiv3
./mvnw spring-boot:run
2

Register a Test Tool

Open http://localhost:8080 and register a simple API tool (e.g., weather API).
3

Test Bridge Manually

Run the bridge in standalone mode:
/usr/local/bin/handsai-mcp mcp
Send a test JSON-RPC message:
{"jsonrpc":"2.0","method":"tools/list","id":1}
You should receive a list of available tools.
4

Test from MCP Client

In Claude Desktop or Antigravity, ask:
“What tools do you have access to?”
The client should list all tools registered in HandsAI.

​
Usage in Action

​
Claude Desktop Example

Claude executing a weather tool from HandsAI: Claude executing HandsAI weather tool Claude sending an email via HandsAI + Resend: HandsAI sending email with Resend

​
Antigravity Example

Antigravity using HandsAI to check weather: Antigravity using HandsAI weather tool

​
Troubleshooting

  1. Verify HandsAI is running: 
    curl http://localhost:8080/mcp/tools/list
  2. Check the bridge logs for connection errors
  3. Ensure no firewall is blocking localhost:8080
  1. Verify the bridge binary path is absolute in the config
  2. Restart the MCP client completely
  3. Check that tools are registered in HandsAI at http://localhost:8080
  4. Test the bridge manually (see Testing section above)
Make the binary executable:
chmod +x /usr/local/bin/handsai-mcp
The bridge caches tool definitions. Restart your MCP client to refresh the tool list.

​
What’s Next?

Register APIs

Start registering external APIs as tools

Use Cases

Explore pre-built integrations and examples

Build docs developers (and LLMs) love

Get started for freeTalk to us