compatible.systems MCP

This repository contains the compatible.systems MCP hub and a reusable Codex plugin for accessing it through Authentik OAuth.

Layout

• mcp-hub/: Node/Bun MCP aggregation hub. It exposes a streamable HTTP MCP endpoint, OAuth protected-resource metadata, health/status routes, and backend adapters for configured MCP services.
• plugins/compatible-systems/: Codex plugin. It runs a local stdio proxy that performs Authentik browser sign-in once with authorization code + PKCE, caches only local OAuth tokens, and forwards MCP requests to https://compatible.systems/mcp.

Hub Runtime

The hub is configured entirely with environment variables. Do not commit secrets.

Minimum public deployment shape:

MCP_HUB_PORT=8098
MCP_HUB_LISTEN_HOST=127.0.0.1
MCP_HUB_BASE_PATH=/mcp
MCP_HUB_PUBLIC_BASE_URL=https://compatible.systems/mcp
MCP_HUB_ALLOW_ANONYMOUS=false
MCP_HUB_AUTH_DISCOVERY_URL=https://idp.compatible.systems/application/o/mcp/.well-known/openid-configuration
MCP_HUB_AUTH_ISSUER=https://idp.compatible.systems/application/o/mcp/
MCP_HUB_AUTH_CLIENT_ID=mcp.compatible.systems

Run locally:

cd mcp-hub
npm install
MCP_HUB_ALLOW_ANONYMOUS=true npm start

Codex Plugin

Install or add plugins/compatible-systems in Codex. On first tool use, the proxy opens Authentik in the browser, listens on a localhost callback for the OAuth authorization-code + PKCE response, and stores the resulting OAuth token at:

~/.cache/compatible-systems-mcp/token.json

Useful plugin environment overrides:

MCP_COMPATIBLE_SYSTEMS_REMOTE_URL=https://compatible.systems/mcp
MCP_COMPATIBLE_SYSTEMS_CLIENT_ID=mcp.compatible.systems
MCP_COMPATIBLE_SYSTEMS_AUTHORIZATION_ENDPOINT=https://idp.compatible.systems/application/o/authorize/
MCP_COMPATIBLE_SYSTEMS_REQUIRED_EMAIL=you@example.com
MCP_COMPATIBLE_SYSTEMS_OPEN_BROWSER=1

No UniFi, Home Assistant, iMessage, or other backend API credentials belong in this repository. Put deployment secrets in the host secret manager and pass them to the hub as environment variables.