Self-hosting HyprMCP

Caution

HyprMCP is still in active development.

We might make BREAKING CHANGES and require difficult migrations.

If you are only interested in our MCP mcp-install-instructions-generator or our mcp-gateway, follow the instructions in the component sections.

Make sure you have familiarized yourself with the Getting Started section.

# Technical Description

Deploying and operating HyprMCP requires a Kubernetes cluster, as Jetski (the orchestrator) will deploy a new MCP Gateway instance for every organization. Jetski creates a Kubernetes custom resource for every organization, whose lifecycle is managed by the Metacontroller.

Additionally, an authentication server is required that authenticates users against Jetski and against MCP servers. Although these servers can theoretically be different instances, we are currently using a single Dex instance for all authentication and authorizations.

# Setup

The setup can be split into two parts:

1. Setting up the Jetski Analytics platform
2. Setting up Jetski MCP Gateway Orchestration

# 1. Jetski Analytics Platform

HyprMCP uses mise to configure your development environment and execute development tasks.

You can get started locally by running the following commands:

Step	Command
Clone the repository	git clone https://github.com/hyprmcp/jetski.git && cd jetski
Install dependencies - Trust mise configuration and install necessary tools	mise trust && mise install
Create Dex secret file	touch .dex.secret.env
Start database and mock SMTP server	docker compose up -d
Set correct host file entry - Add the following entry to your /etc/hosts file: 127.0.0.1 host.minikube.internal, or reconfigure the Dex hostname	(manual file edit)
Start the Backend	mise run serve
Start the Frontend	pnpm run start
Generate demo data	mise run generate

Afterward you can access the frontend at http://localhost:4200 and log in with: admin@example.com / password.

# 2. Setting up Jetski MCP Gateway Orchestration

For setting up the orchestration part of Jetski, a Kubernetes cluster is recommended. We recommend Minikube for local testing. Make sure you have followed all previous steps - especially the /etc/hosts entry is required for Dex to work correctly.

Step	Command
Start a preconfigured Minikube cluster	mise run minikube-start
Start the platform and deploy metacontroller - ⚠️ This will perform operations against the currently configured Kubernetes context!	mise run serve -- --install-controller

Now when configuring a new project, it should get successfully deployed to your Kubernetes cluster.

# Support

We are happy to assist you with any custom setups or questions you might have.