Skip to Content
OperateDeployHybrid MCP servers

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

If you need to connect external AI clients to a self-hosted Arcade runtime without any tunnel — using outbound-only network egress from your VPC — see Warp Pipes instead.

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:

Terminal
arcade login

Start your server with HTTP transport:

Terminal
# 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.

  1. Install ngrok:

    Terminal
    # macOS
brew install ngrok
 
# Or download from https://ngrok.com/download

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

  2. Create a tunnel:

    Terminal
    ngrok http 8000

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

    PLAINTEXT
    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

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:

YAML
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

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

Last updated on
Self-host with HelmOverview