How do I use Vento Remote MCP Connector?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Vento Remote MCP Connector read the temperature from board 1" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Vento Remote MCP Connector

by geromendez199

Overview Schema Related Servers Score Discussions

TypeScript

Hybrid

Vento Remote MCP Connector

CI Status License

Connect Claude, Claude Desktop, and Cursor to any Vento instance via Model Context Protocol

🚀 Quick Deploy

Deploy on Railway

Railway (1-click, railway.json) ⭐ Easiest
Render (Blueprint: render.yaml included)
Fly.io (fly.toml included)
Docker
VPS + Systemd
Cloudflare Tunnel

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

Related MCP server: RegenNexus MCP Server

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

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

Go to claude.ai/app
Click Settings → Custom Connectors
Click Add Custom Connector
Enter:
- Name: Vento
- Server URL: https://your-connector-url.com (public URL of your deployment)
In the request header section, add:
- Key: Authorization
- Value: Bearer YOUR_MCP_AUTH_TOKEN
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

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
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:

VENTO_API_URL is correct and accessible
VENTO_TOKEN is valid
Firewall allows outbound connections
Vento instance is running and healthy

Connector not showing in Claude

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

Actions not executing

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":{}}'

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

Community & Support

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

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch: git checkout -b feature/your-feature
Make changes with tests
Run: npm run lint && npm test && npm run type-check
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!

This server cannot be installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly
Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
OpenAI
open source

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/geromendez199/vento-remote-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server