Junctio

Getting started

Junctio is one container and one volume. The image is ghcr.io/k2so-dev/junctio, built for amd64 and arm64.latest is the last release, edge follows main.

Run it

Fetch the compose file and the environment template:

mkdir junctio && cd junctio
curl -fsSLO https://raw.githubusercontent.com/k2so-dev/junctio/main/compose.yml
curl -fsSL https://raw.githubusercontent.com/k2so-dev/junctio/main/.env.example -o .env

Set JUNCTIO_SECRET in .env to the output of openssl rand -hex 32. The process refuses to start without it, because it is the key that encrypts every stored token. Then:

$docker compose up -d

Open http://localhost:3000 and set an admin password. Running from the source tree works too, withbun install, bun run build:web and bun run start.

Connect a client

  1. Add a server. For a package on npm pick the npx runtime and type the package name. The form previews the exact command.
  2. Create a namespace and put the server in it.
  3. Create an endpoint pointing at that namespace and issue an API key.
  4. Paste the snippet into your client.
claude mcp add --transport http junctio https://mcp.example.com/mcp/main \
  --header "Authorization: Bearer jn_..."

Every client sees the same endpoint. Tools from each upstream are exposed with a prefix, so github__searchand db__query live side by side without colliding. Endpoints covers aggregation, auth modes and protocol negotiation.

Behind a domain

Set JUNCTIO_BASE_URL and JUNCTIO_TRUST_PROXY=true, and terminate TLS in front of the gateway. OAuth does not work over plain HTTP: browsers and MCP clients refuse the redirects. TheCaddy guide is a two-line Caddyfile; Dokploy,Coolify and Portainer have their own pages.

Where to go next

  • Upstream servers: stdio runtimes, remote transports, images, upstream OAuth.
  • Management MCP: let an agent configure the gateway instead of clicking.
  • Explore: the registry, other catalogs, import from a pasted client config.
  • Security audit: scheduled vulnerability checks and what a finding does.
  • Use cases: Claude Code, Cursor, claude.ai connectors, a small team, a VPS.