Arcade
Github Discord
OperateDeploy

Hybrid MCP servers

Outcomes

A hybrid server deployment — also called a self-hosted worker or hybrid worker — runs the on infrastructure you control (on-premises, private cloud, VPC, or any private network) while Arcade’s cloud Engine keeps handling identity, routing, and governance. This gives you the flexibility to access private resources behind a firewall, keep sensitive data inside your network, and customize your environment while leveraging Arcade’s MCP server management and federation capabilities.

You will Learn

  • How to run your server with HTTP transport
  • How to create a secure tunnel to expose it publicly
  • How to register your server in Arcade
  • How to test your server with the Arcade Playground

Prerequisites

How on-premises MCP servers work

You can make your self-hosted server accessible to Arcade Cloud by exposing it through a secure tunnel and registering it as a worker. This allows remote users and services to interact with your without deploying to a cloud platform.

The on-premises server model (a hybrid worker deployment) uses a bidirectional connection between your local environment and Arcade’s cloud engine:

  1. You run the Arcade server in your environment (on-premises, private cloud, VPC, or any private network)
  2. Your server is exposed to Arcade’s cloud engine using a public URL
  3. The Arcade cloud engine routes tool calls to your server
  4. Your server processes the requests and returns responses to the engine

Benefits of on-premises MCP servers

  • Resource access: Reach private databases, internal APIs, and other resources sitting behind your firewall that aren’t accessible from Arcade’s cloud
  • Data control: Keep sensitive data within your environment while still using Arcade’s capabilities
  • Custom environments: Use specific dependencies or configurations required by your
  • Compliance: Meet regulatory requirements by keeping data processing within your infrastructure

Setting up an on-premises MCP server

Setup your MCP Servers

Follow the Creating a MCP Server guide to create your Server.

Start your local MCP Server

Ensure you are logged in to Arcade:

arcade login

Add the environment variables to your shell:

export ARCADE_API_KEY=<your-api-key>
export ARCADE_USER_ID=<your-user-id>
$env:ARCADE_API_KEY="<your-api-key>"
$env:ARCADE_USER_ID="<your-user-id>"

or to a .env file:

.env
ARCADE_API_KEY=<your-api-key>
ARCADE_USER_ID=<your-user-id>

Start your server with HTTP transport:

# Navigate to your entrypoint file
cd my_server/src/my_server

# Run with HTTP transport (default)
uv run server.py
uv run server.py http

Your server will start on http://localhost:8000. Keep this terminal running.

Create a Secure Tunnel

Open a separate terminal and create a tunnel using one of these options:

  • ngrok is easy to set up and works across all platforms.
  • Cloudflare Tunnel provides persistent URLs and advanced features.
  • Tailscale Funnel is ideal for sharing within a team or organization.

ngrok is easy to set up and works across all platforms.

  1. Install ngrok:

    # macOS
brew install ngrok

# Or download from https://ngrok.com/download

    On Windows, install ngrok from ngrok.com/download.

  2. Create a tunnel:

    ngrok http 8000

  3. Copy your URL: Look for the “Forwarding” line in the ngrok output:

    Forwarding  https://abc123.ngrok-free.app -> http://localhost:8000

    Copy the https://abc123.ngrok-free.app URL - this is your public URL.

Pros:

  • Quick setup, no required for basic use
  • Automatic HTTPS
  • Web dashboard to inspect requests

Cons:

  • Free tier URLs change on each restart
  • May show interstitial page for free tier

Cloudflare Tunnel provides persistent URLs and advanced features.

  1. Install cloudflared:

    # macOS
brew install cloudflare/cloudflare/cloudflared

# Or download from https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/

    On Windows, install cloudflared from Cloudflare Tunnel install docs.

  2. Create a tunnel:

    cloudflared tunnel --url http://localhost:8000

  3. Copy your URL: Look for the “Your quick Tunnel has been created” message with your URL.

Pros:

  • Free tier includes persistent URLs (with setup)
  • Built-in DDoS protection
  • Access control features

Cons:

  • Requires Cloudflare for persistent URLs
  • More complex setup for advanced features

Tailscale Funnel is ideal for sharing within a team or organization.

  1. Install Tailscale:

    # macOS
brew install tailscale

# Or download from https://tailscale.com/download

    On Windows, install Tailscale from tailscale.com/download.

  2. Authenticate:

    tailscale up

  3. Create a funnel:

    tailscale funnel 8000

  4. Get your URL: Tailscale will display your funnel URL (e.g., https://my-machine.tail-scale.ts.net)

Pros:

  • Persistent URLs tied to your machine
  • Private by default (only shared with specified )
  • No bandwidth limits

Cons:

  • Requires Tailscale
  • Best for team/organization use cases

Register your MCP Server in Arcade

Once you have a public URL, register your server in the Arcade dashboard to make it accessible through the .

  1. Navigate to the Servers page in your Arcade dashboard

  2. Click “Add Server”

  3. Fill in the registration form:

    • ID: Choose a unique identifier (e.g., my-mcp-server)
    • Server Type: Select “Arcade”
    • URL: Enter your public tunnel URL from Step 2
    • Secret: Enter a secret for your server (or use dev for testing)
    • Timeout: Configure request timeout (default: 30s)
    • Retry: Configure retry attempts (default: 3)

  4. Click “Create”

Here’s an example of a configuration:

ID: my-mcp-server
Server Type: Arcade
URL: https://abc123.ngrok-free.app
Secret: my-secure-secret-123
Timeout: 30s
Retry: 3

Test the connection to your MCP Server

You can now test your Server by making requests using the Playground, or an MCP client:

  1. Go to the Arcade Playground

  2. Select your server from the dropdown

  3. Choose a from your server

  4. Execute the with test parameters

  5. Verify the response:

    • Check that the response is correct
    • View request logs in your local server terminal
    • Inspect the tunnel dashboard for request details
  1. Use an app that supports clients, like AI assistants and IDEs:
  2. Enable your Server from the list of available
  3. Verify that the response is correct and you see request logs in your Server

Key Concepts

  • HTTP Transport Run your server with HTTP transport to expose your via a REST/SSE API
  • Secure Tunnels Create a secure tunnel to expose your server publicly
  • Arcade Registration Register your server in Arcade to make it accessible through the
  • Playground Testing Test your server with the Arcade Playground

Best practices

  • Persistent URLs: For production use, set up a persistent public URL rather than ephemeral ones
  • TLS: Use a TLS-enabled URL for production use
  • Monitoring: Set up monitoring for your Server to ensure availability

Troubleshooting

  • Connection issues: Ensure your public URL is accessible and that your local Server is running
  • Timeout errors: If your Server takes too long to respond, increase the timeout value in the configuration

Next steps

Edit on GitHub

Last updated on

Arcade Worker

What the Arcade Worker does in a self-hosted deployment and the settings operators control

Overview

Connect end-user identity providers and configure how gateways authenticate users

On this page

How on-premises MCP servers workBenefits of on-premises MCP serversSetting up an on-premises MCP serverSetup your MCP ServersStart your local MCP ServerCreate a Secure TunnelRegister your MCP Server in ArcadeTest the connection to your MCP ServerKey ConceptsBest practicesTroubleshootingNext steps