How to Use the Balena MCP in Windsurf

Q: How do I connect the Balena MCP Server to Windsurf?

Add the Vinkius endpoint to your /.codeium/windsurf/mcpconfig.json file. You can also use the Settings menu under Cascade to add the server URL. Hit refresh in the MCP panel and Cascade will auto-discover the tools.

Q: Can Windsurf update Balena device tags automatically?

Yes. Cascade chains listdevices to find your target hardware, then runs createdevicetag on the results. You just give it the filtering criteria.

Q: How do I check my current Balena API keys?

Ask Cascade to run listapikeys. It will return your active keys and token details directly in the chat window.

Manage your IoT edge fleets directly from Windsurf. Cascade chains Balena operations without breaking your coding flow.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Balena MCP to Windsurf

Create your Vinkius account to connect Balena to Windsurf and route execution through our secure gateway. The platform manages server hosting, runtime updates, and security layers. Configuration requires no manual server provisioning.

GDPR Free for Subscribers

Setup Balena with Windsurf

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Windsurf MCP Server for Fleet Management

Balena manages IoT fleets and edge devices, letting you track hardware directly from your editor. Windsurf reads your context and triggers `list_fleets` or `list_organizations` to figure out exactly which applications need updates. Cascade takes over from there. You tell it to find offline hardware, and it fires off `list_devices` with OData filters to grab the UUIDs. No jumping between the dashboard and your code.

Chain Environment Variable Updates

Pushing new configurations to distributed hardware usually means clicking through a web interface. You can skip that by asking your agent to run `create_device_env_var` across a specific target group. The autonomous engine checks the current state using `list_releases` first. Then it applies the new variables and tags the updated machines via `create_device_tag` in one continuous sequence.

Automate OS Image Downloads

Grabbing the right operating system for a specific board type requires matching exact versions. Your client pulls the hardware specs and runs `list_os_versions` to find the compatible builds. Once it identifies the correct target, it executes `get_os_download_url`. You get the exact balenaOS image link dropped right into your terminal or build script setup.

Setup guide

Set up Balena MCP in Windsurf

Prerequisites

Windsurf IDE installed (macOS, Windows, or Linux)
Active Vinkius subscription with a valid endpoint token

1

Open MCP configuration

Click the Cascade assistant icon in the sidebar, then click the hammer icon (🔨) at the top of the panel. Select "Configure" to open ~/.codeium/windsurf/mcp_config.json.
2

Add the Balena MCP

Paste the JSON snippet shown on the right into the mcpServers object. Replace [YOUR_TOKEN_HERE] with your endpoint token from cloud.vinkius.com.
3

Refresh MCPs

Go back to the hammer icon (🔨) in Cascade and click "Refresh". Windsurf will detect the new server. No full restart is needed — the connection is hot-reloaded.
4

Verify in Cascade

Start a new Cascade conversation and ask something like "Show my Balena payment history." If connected, Cascade will call the Balena tools directly. You will see a green dot next to the server name in the MCP panel.

mcp_config.json

{
  "mcpServers": {
    "balena-mcp": {
      "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
    }
  }
}

Get your connection token →

Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by Balena. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.

Why Choose Vinkius

Vinkius connects your tools to AI with real-time monitoring and automatic cost savings — all from one dashboard.

Connect Balena now

Real-time monitoring

Live

visibility into every interaction

Connect your favorite tools to your AI and see exactly what's happening — every request, every response, in real time.

Built-in savings

60%

lower AI costs

Vinkius compresses data between your apps and your AI automatically. Lower bills every month — no configuration required.

Single dashboard

One

place for every integration

Every tool your AI connects to, managed from a single screen. One account, complete control.

Common questions about Balena MCP in Windsurf

Add the Vinkius endpoint to your ~/.codeium/windsurf/mcp_config.json file. You can also use the Settings menu under Cascade to add the server URL. Hit refresh in the MCP panel and Cascade will auto-discover the tools.

Yes. Cascade chains `list_devices` to find your target hardware, then runs `create_device_tag` on the results. You just give it the filtering criteria.

The server supports standard $filter, $select, and $expand queries. Your agent uses these to narrow down API responses, like finding specific device UUIDs or fleet slugs.

Ask Cascade to run `list_api_keys`. It will return your active keys and token details directly in the chat window.

Vinkius runs this MCP Server in an ephemeral V8 Isolate sandbox. Your device UUIDs, environment variables, and API keys pass through a zero-trust environment. The container destroys itself immediately after the request finishes.

Use it with your favorite AI tools

Connect this server to Cursor, Claude, VS Code, and more.

OpenAI Agents SDK sdk-python

Google ADK sdk-python

Pydantic AI sdk-python

Vercel AI SDK sdk-typescript