Skip to content

Customizing the Admin UI

The Admin experience is shipped as a Jinja template (mcpgateway/templates/admin.html) with supporting assets in mcpgateway/static/. It uses HTMX for request/response swaps, Alpine.js for light-weight reactivity, and the Tailwind CDN for styling. There are no environment-variable knobs for colors or layout—the way to customise it is to edit those files (or layer overrides during deployment).

Technology Stack

Library Version Purpose
HTMX 2.0.3 AJAX interactions, HTML-over-HTTP (bundled via npm/Vite)
Alpine.js 3.x Lightweight reactive components
Tailwind CSS Pre-compiled Utility-first styling (built from source)
CodeMirror 5.65.18 Syntax-highlighted code editing
Chart.js - Data visualization
Marked.js - Markdown rendering
DOMPurify - XSS sanitization
Font Awesome - Icons

All vendor libraries are bundled locally in mcpgateway/static/vendor/ for air-gapped deployments. Enable with MCPGATEWAY_UI_AIRGAPPED=true. See Air-Gapped Mode.

Feature Flags to Enable the UI

Ensure the Admin interface is turned on before making changes:

MCPGATEWAY_UI_ENABLED=true
MCPGATEWAY_ADMIN_API_ENABLED=true

Other UI-related settings:

  • MCPGATEWAY_UI_AIRGAPPED (boolean, default: false) – Load CSS/JS from local vendor files instead of CDNs
  • MCPGATEWAY_UI_TOOL_TEST_TIMEOUT (milliseconds) – Timeout for the "Test Tool" action in the Tools catalog

Every other visual/behaviour change is code-driven.

  1. Copy .env.example to .env, then set: 

    DEV_MODE=true
RELOAD=true
    This enables template + static reloads while you work.

  2. Start the dev server: make dev (serves the UI at http://localhost:8000).

  3. Edit any of the following and refresh your browser:

  4. mcpgateway/templates/admin.html

  5. mcpgateway/static/admin.css
  6. mcpgateway/static/admin.js

  7. Additional assets under mcpgateway/static/

  8. Commit the customised files or prepare overrides for your deployment target (see Deploying Overrides).

Tip: keep your changes on a dedicated branch so that rebase/merge with upstream remains manageable.

File Layout Reference

Path Description
mcpgateway/templates/admin.html Single-page admin template containing header, navigation, tables, modals, metrics, etc.
mcpgateway/static/admin.css Tailwind-friendly overrides (spinners, tooltips, table tweaks).
mcpgateway/static/admin.js Behaviour helpers (form toggles, request utilities, validation).
mcpgateway/static/images/ Default logo, favicon, and imagery used in the UI.

All static assets are served from /static/ and respect ROOT_PATH when the app is mounted behind a proxy.

Branding Essentials

Document Title & Header

  • Update the <title> element and the main <h1> block near the top of admin.html with your organisation's name.

  • The secondary copy and links (Docs, GitHub star) live in the same header section—edit or remove them as needed.

Logo & Favicon

  • Replace the default files in mcpgateway/static/ (or add your own under static/images/).

  • Update the <link rel="icon"> and <img src="..."> references in admin.html to point to your assets, e.g. 

    <link rel="icon" href="{{ root_path }}/static/images/company-favicon.ico" />
<img src="{{ root_path }}/static/images/company-logo.svg" class="h-8" alt="Company logo" />

Colors & Tailwind

  • Tailwind is pre-compiled into mcpgateway/static/css/tailwind.min.css from tailwind.config.js with darkMode: "class".

  • To customise colours, fonts, animations or other Tailwind settings, edit tailwind.config.js in the project root: 

    // tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: { brand: "#1d4ed8", accent: "#f97316" },
      fontFamily: { display: ['"IBM Plex Sans"', "sans-serif"] },
    },
  },
};
    After editing, rebuild the CSS: 
    make build-css       # local development
    For Docker builds, the CSS is compiled during the node-builder stage, so changes to tailwind.config.js are picked up automatically on the next container build.

  • For bespoke CSS (animations, overrides), append to admin.css or include a new stylesheet in the <head>: 
    <link rel="stylesheet" href="{{ root_path }}/static/css/custom.css" />

Theme Toggle

  • The dark/light toggle persists a darkMode value in localStorage. Change the default by altering the x-data initialiser in the <html> tag if you want to default to dark: 
    x-data="{ darkMode: JSON.parse(localStorage.getItem('darkMode') || 'true') }"

Behaviour Customisation

  • admin.js powers form helpers (e.g. locking the Tool URL field when MCP is selected) and general UX‐polish. Append your scripts there or include a new JS file at the end of admin.html.

  • Use HTMX hooks (htmx:beforeSwap, htmx:afterSwap, etc.) if you need to intercept requests.

  • Alpine components live on each panel (look for x-data="tabs", etc.)—extend them by adding properties/methods in the x-data object.

  • Avoid writing raw innerHTML with user data to preserve the UI's XSS protections; prefer textContent.

  • Lazy-loaded sections (bulk import, A2A, teams, etc.) are clearly marked in the template—remove panels you don't need.

Key Template Anchors

Search for these comments in admin.html when hunting for specific areas:

  • <!-- Navigation Tabs --> – top-level tab buttons.
  • <!-- Status Cards --> – summary cards for totals.
  • <!-- Servers Table -->, <!-- Tools Table -->, <!-- Resources Table -->, etc. – per-resource CRUD grids.
  • <!-- Bulk Import Modal -->, <!-- Team Modal --> – modal dialogs.
  • id="metadata-tracking", id="a2a-agents", id="team-management" – advanced sections you can prune or reorder.

Make your edits and refresh the browser to confirm behaviour.

Deploying Overrides

When packaging the gateway:

  • Bake into the image – copy customised templates/static files during the container build.

  • Mount at runtime – overlay files via volumes: 

    docker run \
  -v $(pwd)/overrides/admin.html:/app/mcpgateway/templates/admin.html:ro \
  -v $(pwd)/overrides/static:/app/mcpgateway/static/custom:ro \
  ghcr.io/ibm/mcp-context-forge:1.0.0-RC-3
    Then update template references to point at static/custom/....

  • Fork + rebase – maintain a thin fork that carries your branding patches.

In Kubernetes, place customised assets in a ConfigMap/Secret and mount over the default paths (/app/mcpgateway/templates/admin.html, /app/mcpgateway/static/). Roll the deployment after changes so the pod picks up the new files.

Testing Checklist

  1. make dev – confirm the UI renders, tabs switch, and tables load as expected.

  2. Optional: pytest tests/playwright/ -k admin – run UI smoke tests if you altered interaction logic.

  3. Verify in a staging/production-like environment that:

  4. Static assets resolve behind your proxy (ROOT_PATH/APP_DOMAIN).

  5. Authentication flows still succeed (basic + JWT).

  6. Any branding assets load quickly (serve them via CDN if heavy).

  7. Document your customisations internally so future upgrades know which sections were changed.