Vento Remote Connector

Vento Remote MCP is a production-ready remote server that bridges Claude (claude.ai, mobile app, Claude Desktop, Claude Code, and the Anthropic API) with any Vento instance (self-hosted or cloud.vento.build). It enables AI assistants to read sensor values, monitor device status, and execute real-world actions through Vento boards and agents.

What is Vento?

Vento is an AI control and automation platform for devices, machines, and spaces:

• Boards: Visual dashboards composed of cards representing sensors (value cards) and actuators (action cards)
• AI Agents: LLM-powered decision loops that observe the world, make decisions, and take action
• Device Integration: Native support for ESP32/ESPHome, Android phones, Go/Python agents, and custom MQTT devices
• Real-time Control: MQTT-based instant communication with physical devices and sensors

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                      CLAUDE ECOSYSTEM                           │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────┐    │
│  │  Claude.ai   │  │Claude Desktop│  │   Claude Code      │    │
│  └──────┬───────┘  └──────┬───────┘  └──────┬─────────────┘    │
│         └────────────┬────────────────────────┘                 │
│                      │                                          │
│                      ▼                                          │
│         ┌─────────────────────────────┐                        │
│         │ Anthropic API / MCP Client  │                        │
│         └────────────┬────────────────┘                        │
└──────────────────────┼─────────────────────────────────────────┘
                       │
                       │ HTTP (Bearer Token Auth)
                       │
┌──────────────────────▼─────────────────────────────────────────┐
│          VENTO REMOTE MCP CONNECTOR (This Project)             │
│  ┌────────────────────────────────────────────────────────────┐│
│  │ • Tool Registry (6 MCP tools for reading/controlling)      ││
│  │ • MCP Protocol Handler                                      ││
│  │ • Vento API Client                                          ││
│  │ • Authentication & Rate Limiting                            ││
│  └────────────────────────────────────────────────────────────┘│
└──────────────────────┬─────────────────────────────────────────┘
                       │
                       │ REST (Bearer Token Auth)
                       │
┌──────────────────────▼─────────────────────────────────────────┐
│        VENTO CORE API (Your Vento Instance)                    │
│  ┌────────────────────────────────────────────────────────────┐│
│  │ • /api/boards/v1 - Boards & Cards Management              ││
│  │ • /api/agents/v1 - AI Agents                              ││
│  │ • /api/devices/v1 - Device Registry                       ││
│  └────────────────────────────────────────────────────────────┘│
└──────────────────────┬─────────────────────────────────────────┘
                       │
                       ▼
          ┌──────────────────────────────┐
          │  PHYSICAL WORLD (Real Actions)│
          │  • IoT Devices (ESP32)        │
          │  • Motors & Sensors           │
          │  • Android Phones             │
          │  • MQTT Network               │
          └──────────────────────────────┘

Quick Start

Prerequisites

• Node.js 20+ or Docker
• A running Vento instance (local or remote)
• Vento API token
• Anthropic API key (for claude.ai integration)

Installation

Option 1: Docker (Recommended)

# Clone the repository
git clone https://github.com/geromendez199/vento-remote-mcp.git
cd vento-remote-mcp

# Configure environment
cp .env.example .env
# Edit .env with your Vento credentials

# Start the connector
docker compose up

Option 2: Local Development

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your Vento credentials

# Start in development mode
npm run dev

# Or build and run production
npm run build
npm start

Option 3: Deploy to Cloud

Railway

Deploy on Railway

Render

Deploy to Render

Fly.io

fly launch --repo https://github.com/geromendez199/vento-remote-mcp
fly secrets set MCP_AUTH_TOKEN=your-token
fly secrets set VENTO_API_URL=https://your-vento-instance.com
fly secrets set VENTO_TOKEN=your-vento-api-token
fly deploy

VPS + Cloudflared

# Deploy to VPS
git clone https://github.com/geromendez199/vento-remote-mcp.git
cd vento-remote-mcp
npm install && npm run build

# Install systemd service
sudo cp systemd/vento-remote-mcp.service /etc/systemd/system/
sudo systemctl enable vento-remote-mcp
sudo systemctl start vento-remote-mcp

# Expose via Cloudflared tunnel
cloudflared tunnel create vento-mcp
cloudflared tunnel route dns vento-mcp your-domain.com
cloudflared tunnel run --token $TUNNEL_TOKEN

Configuration

Create .env file:

# Server
PORT=3000
LOG_LEVEL=info

# Security
MCP_AUTH_TOKEN=<generate with: openssl rand -hex 32>

# Vento Connection
VENTO_API_URL=http://localhost:8000
VENTO_TOKEN=your-vento-api-token

# Rate Limiting
RATE_LIMIT_ENABLED=true
RATE_LIMIT_REQUESTS_PER_MINUTE=60

Using with Claude

Claude.ai or Claude Mobile App

1. Go to claude.ai/app
2. Click Settings → Custom Connectors
3. Click Add Custom Connector
4. Enter:
   • Name: Vento
   • Server URL: https://your-connector-url.com (public URL of your deployment)
5. In the request header section, add:
   • Key: Authorization
   • Value: Bearer YOUR_MCP_AUTH_TOKEN
6. Save

Now you can ask Claude to "list my Vento boards" or "turn on the pump".

Claude Desktop

Add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "vento": {
      "url": "https://your-connector-url.com",
      "auth": {
        "type": "bearer",
        "token": "YOUR_MCP_AUTH_TOKEN"
      }
    }
  }
}

Claude Code

claude mcp add --transport http vento https://your-connector-url.com \
  --header "Authorization: Bearer YOUR_MCP_AUTH_TOKEN"

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "vento": {
      "url": "https://your-connector-url.com",
      "auth": {
        "type": "bearer",
        "token": "YOUR_MCP_AUTH_TOKEN"
      }
    }
  }
}

Available Tools

All tools are read-only unless noted otherwise.

Tool	Description	Use Case
vento_list_boards	List all boards with name and description	Discover available boards
vento_get_board	Get complete board state: cards and current values	Monitor sensor data and see available actions
vento_get_card_value	Get current value of a specific sensor card	Check single sensor reading
vento_list_devices	List connected devices (ESP32, Android, etc.)	Monitor device network status
vento_run_action	Execute an action card ⚠️	Control pumps, motors, GPIO, send alerts
vento_send_to_agent	Send message to Vento AI agent	Trigger automation flows using natural language

Every tool accepts an optional instance argument to target a specific Vento instance when VENTO_INSTANCES is configured (see below).

Production Features

Tool permissions (read-only mode)

# Allowlist specific tools (unset = all)
ALLOWED_TOOLS=vento_list_boards,vento_get_board,vento_get_card_value

# Or just hide destructive tools (vento_run_action)
ALLOW_DESTRUCTIVE_TOOLS=false

Blocked tools are removed from discovery and rejected at execution — a client that skips tools/list still can't call them.

Multiple Vento instances

VENTO_INSTANCES={"staging":{"url":"https://staging.vento.example.com","token":"tok"}}

The primary instance (VENTO_API_URL) is always available as default. Claude can then say: "compare the temperature on production and staging" — each tool call routes via its instance argument.

Observability

Endpoint	Purpose
GET /health	Readiness: pings Vento, reports latencyMs (503 when degraded)
GET /health/live	Liveness: cheap, no upstream calls
GET /metrics	Prometheus metrics (bearer-auth protected)
GET /info	Server version, instances, exposed tools with danger levels

Metrics include request duration histograms, Vento API call counters, per-tool execution counters, auth failures, rate-limited requests, and cache hit/miss. Every HTTP response carries an X-Request-Id that appears in all correlated log lines.

Rate limiting & caching

• Per-token rate limiting: RATE_LIMIT_REQUESTS_PER_MINUTE (default 60) plus RATE_LIMIT_BURST_PER_SECOND (default 10). Clients are keyed by token hash.
• Board reads are cached for CACHE_TTL_SECONDS (default 30) and invalidated automatically when an action executes on that board. Live sensor reads are never cached.

Security

⚠️ Important: This connector controls real physical devices. Use with caution.

Authentication

1. Claude ↔ Connector: Bearer token in HTTP headers

   • Set MCP_AUTH_TOKEN to a strong random value (min 32 characters)
   • Generate: openssl rand -hex 32
   • Never commit tokens to version control

2. Connector ↔ Vento: API token in environment variables

   • Store VENTO_TOKEN in environment, not in code
   • Use separate tokens for dev/prod
   • Rotate regularly

Permissions

• Use ALLOW_DESTRUCTIVE_TOOLS=false for read-only deployments
• Use ALLOWED_TOOLS to expose only specific tools
• Bearer comparison is timing-safe; auth failures are counted in /metrics
• Rate limiting is on by default (per-token, with burst control)

Best Practices

✅ DO:

• Use strong, randomly generated tokens
• Rotate tokens regularly
• Deploy over HTTPS only
• Monitor logs for suspicious activity
• Restrict Vento board access to essential actions
• Test actions in development first

❌ DON'T:

• Commit tokens to git
• Use the same token across multiple deployments
• Expose the connector to untrusted networks
• Disable authentication
• Connect to production Vento with test credentials

Development

Project Structure

vento-remote-mcp/
├── src/
│   ├── index.ts              # Server bootstrap (stdio or HTTP)
│   ├── server.ts             # MCP tool registration
│   ├── config.ts             # Environment validation (zod)
│   ├── auth.ts               # Bearer token middleware
│   ├── vento/
│   │   ├── client.ts         # HTTP client for Vento API
│   │   └── types.ts          # TypeScript types for Vento
│   └── tools/                # Individual tool implementations
│       ├── listBoards.ts
│       ├── getBoard.ts
│       ├── getCardValue.ts
│       ├── listDevices.ts
│       ├── runAction.ts
│       └── sendToAgent.ts
├── test/                     # Unit and integration tests
├── docs/
│   ├── vento-api.md          # Complete API reference
│   └── deploy.md             # Deployment guides
├── Dockerfile                # Multi-stage Docker build
├── docker-compose.yml        # Local dev environment
├── .env.example              # Configuration template
└── README.md                 # This file

Running Tests

# Run all tests
npm test

# Watch mode
npm test -- --watch

# Coverage report
npm test -- --coverage

# Interactive UI
npm run test:ui

Type Checking & Linting

# Type check
npm run type-check

# Lint
npm run lint

# Fix lint issues
npm run lint -- --fix

End-to-End Testing

# Start local Vento + Connector
docker compose up

# In another terminal, test with the MCP inspector
npx @modelcontextprotocol/inspector ts-node src/index.ts

# Or test HTTP endpoints
curl http://localhost:3000/health
curl -H "Authorization: Bearer test-token" http://localhost:3000/info

Roadmap

• Core MCP server with stdio transport
• HTTP transport support for remote deployment
• Bearer token authentication
• OAuth 2.1 support for Anthropic directory submission
• Tool filtering and per-conversation permissions
• Rate limiting and request logging
• WebSocket transport support
• Multiple Vento instance support
• Board state caching and subscriptions
• Custom tool creation from Vento agents
• Anthropic MCP directory submission

Troubleshooting

"Invalid authorization header"

Make sure you're using Bearer token authentication:

Authorization: Bearer YOUR_MCP_AUTH_TOKEN

"Failed to connect to Vento API"

Check:

1. VENTO_API_URL is correct and accessible
2. VENTO_TOKEN is valid
3. Firewall allows outbound connections
4. Vento instance is running and healthy

Connector not showing in Claude

1. Verify the public URL is accessible: curl https://your-url.com/health
2. Check token is correct in Claude settings
3. Wait 1-2 minutes for Claude to sync
4. Restart Claude app if needed

Actions not executing

1. Test directly with curl:

   curl -X POST https://your-url.com/mcp \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"method":"initialize","params":{}}'
   

2. Check Vento board exists and action is enabled
3. Review logs: docker compose logs connector

Community & Support

• Discord: Join Vento Discord
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Make changes with tests
4. Run: npm run lint && npm test && npm run type-check
5. Submit a pull request

See CONTRIBUTING.md for details.

License

MIT License - See LICENSE for details

Credits

Built with ❤️ for the Vento community by Gero Méndez

Special thanks to:

• Anthropic for Claude and the Model Context Protocol
• Protofy for Vento

---

Want to contribute, report a bug, or suggest a feature? Open an issue or discussion on GitHub!