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).
Feature Flags to Enable the UI¶
Ensure the Admin interface is turned on before making changes:
The only other related tuning knob is:
MCPGATEWAY_UI_TOOL_TEST_TIMEOUT
(milliseconds) – timeout for the "Test Tool" action triggered from the Tools catalog.
Every other visual/behaviour change is code-driven.
Recommended Editing Workflow¶
- Copy
.env.example
to.env
, then set: This enables template + static reloads while you work. - Start the dev server:
make dev
(serves the UI at http://localhost:8000). - Edit any of the following and refresh your browser:
mcpgateway/templates/admin.html
mcpgateway/static/admin.css
mcpgateway/static/admin.js
- Additional assets under
mcpgateway/static/
- 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 ofadmin.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 understatic/images/
). - Update the
<link rel="icon">
and<img src="...">
references inadmin.html
to point to your assets, e.g.
Colors & Tailwind¶
- Tailwind is initialised in
admin.html
viahttps://cdn.tailwindcss.com
withdarkMode: "class"
. - Add a custom config block to extend colours/fonts and swap utility classes, for example:
- For bespoke CSS (animations, overrides), append to
admin.css
or include a new stylesheet in the<head>
:
Theme Toggle¶
- The dark/light toggle persists a
darkMode
value inlocalStorage
. Change the default by altering thex-data
initialiser in the<html>
tag if you want to default to dark:
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 ofadmin.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 thex-data
object. - Avoid writing raw
innerHTML
with user data to preserve the UI's XSS protections; prefertextContent
. - 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: Then update template references to point at
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:0.7.0
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¶
make dev
– confirm the UI renders, tabs switch, and tables load as expected.- Optional:
pytest tests/playwright/ -k admin
– run UI smoke tests if you altered interaction logic. - Verify in a staging/production-like environment that:
- Static assets resolve behind your proxy (
ROOT_PATH
/APP_DOMAIN
). - Authentication flows still succeed (basic + JWT).
- Any branding assets load quickly (serve them via CDN if heavy).
- Document your customisations internally so future upgrades know which sections were changed.