export SKGATE=https://skgate.example.com KEY=sk-...
curl -s $SKGATE/v1/models -H "Authorization: Bearer $KEY"
curl -s $SKGATE/v1/chat/completions -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"<id from /v1/models>","messages":[{"role":"user","content":"Say hi"}]}'

export OPENAI_BASE_URL=https://skgate.example.com/v1 OPENAI_API_KEY=sk-...

from openai import OpenAI

client = OpenAI()  # reads the two variables above
r = client.chat.completions.create(model="grok-latest", messages=[{"role": "user", "content": "Say hi"}])
print(r.choices[0].message.content)

Map grok-latest to the latest available model. Change the target in this one place and every app using grok-latest is upgraded at once, with no client config changes.

Grok > Details > Model aliases: alias grok-latest, target the newest model in the list (for example grok-4.7), Save.

client sends   {"model": "grok-latest", ...}
skgate sends   {"model": "grok-4.7", ...}

Aliases are listed first in /v1/models.

Needs the latest image and Grok signed in. The first time, Pick MCP helper model next to the button opens the model picker right on the page.

mcp upstreams > Add upstream > Type managed (package or repository):

1. MCP source URL / package, one of:

   Source	Runs as
   @modelcontextprotocol/server-everything	npm package, npx
   pypi:mcp-server-time	PyPI package, uvx
   https://github.com/example-org/notes-mcp	git repo: clone, install, run (private: Access token)

2. Suggest configuration. skgate fetches the README and manifests (package.json, pyproject.toml, server.json), the MCP helper model proposes command, args, install step and env names (marked secret or not, required or optional), and the Manual configuration fields are filled in with a confidence and any warnings. Nothing is saved yet. Point it at the repo, fill in the variables it needs, and it just works.

3. Set an alias, fill in the variables you need (empty ones are not passed to the server), Save. The server is at https://skgate.example.com/mcp/<alias>.

If the button is greyed out, hover it: sign in to Grok on status, or use Pick MCP helper model beside it.

Hosted connectors use OAuth (leave client ID and secret empty). Scripts and CLIs send a key:

{"mcpServers": {"skgate": {"type": "http", "url": "https://skgate.example.com/mcp/<alias>",
  "headers": {"Authorization": "Bearer sk-..."}}}}

On a RAM-constrained homelab, idle MCP servers should cost nothing. Managed servers (npx, uvx, git) are child processes of skgate. By default (Lifecycle on-demand) one starts on its first request and stops after 10 minutes without requests; the next request starts it again.

before   3 MCP servers = 3 containers, always running
after    1 skgate container; 0 server processes while idle, 1 per server in use

stopped  --request-->  starting  -->  running  --10 min idle-->  stopped

• Default is on-demand; Lifecycle always-on starts the server at boot instead.
• The first request after a stop waits until the server answers initialize (up to 60 s).
• A server with a request in flight is never stopped. Stopping is SIGTERM, then SIGKILL after 5 s.
• Idle time is idleTimeoutSeconds in import JSON (default 600; not in the form):

{"mcpServers": {"time": {"command": "uvx", "args": ["mcp-server-time"], "skgate": {"idleTimeoutSeconds": 120}}}}

• The aggregated /mcp includes remote and always-on upstreams marked In /mcp. On-demand servers are left out, so /mcp never starts them. Point a client at /mcp/<alias> to use one.
• Remote upstreams have no process; there is nothing to idle.
• An admin Stop keeps a server stopped until Start or Restart.

mcp upstreams > import JSON > paste > Import. Needs the latest image.

{"mcpServers": {"everything": {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-everything"]}}}

Served at https://skgate.example.com/mcp/everything. For Python servers use "command": "uvx", "args": ["<package>"].

mcp upstreams > import JSON > paste > Import. skgate clones the repo, runs install, then the command.

{"mcpServers": {"notes": {"command": "node", "args": ["server.js"],
  "skgate": {"gitUrl": "https://github.com/example-org/notes-mcp.git", "gitRef": "main", "install": "npm ci"}}}}

mcp upstreams > Add upstream > Type remote (URL), or import:

{"mcpServers": {"docs": {"type": "http", "url": "https://mcp.example.com/mcp",
  "headers": {"Authorization": "Bearer ..."}}}}

1. xAI, Use Grok in OpenCode
2. OpenAI, Sign in with ChatGPT
3. Anthropic, Legal and compliance
4. Google, Gemini CLI terms
5. GitHub, Copilot now supports OpenCode

services:
  skgate:
    container_name: skgate
    image: ghcr.io/helv-io/skgate:latest
    restart: always
    network_mode: web   # existing Docker network shared with Traefik; no ports needed
    environment:
      - PUBLIC_URL=https://skgate.example.com   # the public https origin
      - OIDC_ISSUER=https://auth.example.com
      - OIDC_CLIENT_ID=skgate
      - OIDC_CLIENT_SECRET=change-me
    volumes:
      - ./data:/data
    healthcheck:
      test: ["CMD", "/skgate", "healthcheck"]
      interval: 30s
      timeout: 5s
      retries: 3
    labels:
      # no forward-auth middleware on /v1, /mcp, /authorize, /token, /register, /.well-known
      - traefik.enable=true
      - traefik.http.routers.skgate.rule=Host(`skgate.example.com`)
      - traefik.http.routers.skgate.entryPoints=websecure
      - traefik.http.services.skgate.loadbalancer.server.port=8080

server {
    listen 443 ssl;
    http2 on;
    server_name skgate.example.com;
    ssl_certificate     /etc/ssl/skgate/fullchain.pem;
    ssl_certificate_key /etc/ssl/skgate/privkey.pem;

    client_max_body_size 32m;                         # skgate accepts up to 32 MB

    location / {
        proxy_pass http://skgate:8080;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header Host $host;                  # keep Host
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;                          # SSE streaming
        proxy_read_timeout 3600s;                     # long streams
        proxy_send_timeout 3600s;
    }
}

skgate.example.com {
    # Host and X-Forwarded-* are set by default; no body limit, no response timeout
    reverse_proxy skgate:8080 {
        flush_interval -1                             # SSE streaming
    }
}

defaults
    mode http
    timeout connect 5s
    timeout client  1h                                # long streams
    timeout server  1h
    timeout tunnel  1h

frontend https
    bind :443 ssl crt /etc/haproxy/certs/skgate.pem alpn h2,http/1.1
    option forwardfor                                 # X-Forwarded-For; Host is kept, responses are not buffered
    http-request set-header X-Forwarded-Proto https
    default_backend skgate

backend skgate
    option httpchk GET /healthz
    server skgate skgate:8080 check

# a2enmod ssl proxy proxy_http headers
<VirtualHost *:443>
    ServerName skgate.example.com
    SSLEngine on
    SSLCertificateFile    /etc/ssl/skgate/fullchain.pem
    SSLCertificateKeyFile /etc/ssl/skgate/privkey.pem

    # keep Host
    ProxyPreserveHost On
    RequestHeader set X-Forwarded-Proto "https"
    # long streams
    ProxyTimeout 3600
    # flushpackets: no buffering (SSE)
    ProxyPass        / http://skgate:8080/ flushpackets=on
    ProxyPassReverse / http://skgate:8080/
</VirtualHost>