Use this today: https://mcp.ux4g.gov.in/mcp — staging, public, read-only.
This is a lookup service for AI coding agents. It answers "what is the real UX4G class name / widget / token for this?" so an agent stops guessing.
| Endpoint | Use it for | |
|---|---|---|
| Staging | https://mcp.ux4g.gov.in/mcp |
everything today — testing, feedback, day-to-day work |
| Production | https://mcp.ux4g.gov.in/mcp |
not live yet; DNS is not provisioned |
Both serve the same index and the same six tools. Point at staging until production is announced — a config written against production now will simply fail to resolve.
Every example below uses staging. To move to production later, change the host and nothing else.
Earlier instructions pointed at
ux4g-mcp.netlify.app. That host is retired — update any config you still have.
Ask any AI to "build a login page for a government portal" and it writes this:
<div class="form-group">
<label class="form-label">Aadhaar number</label>
<input class="form-control" inputmode="numeric">
</div>
That is Bootstrap. It is what a department ships today when a developer asks an AI for help, and it looks nothing like a Government of India service.
UX4G class names cannot be guessed. They are not Bootstrap's, not Tailwind's,
and they change between releases — ux4g-btn-md at the retired 3.2.0 is ux4g-btn-m
at 3.3.0, and both are live on the CDN right now. A wrong class name does not
error — it renders unstyled, silently, and ships that way.
With the server connected, the same prompt produces real UX4G markup with the correct classes for the version the project actually uses.
Measured on 52 tasks, one agent, one run each:
| Without the server | With it | |
|---|---|---|
| UX4G names that exist | 0% | 96.2% |
| Tasks using UX4G at all | 0 / 52 | 50 / 52 |
| Invented names | — | 0 |
| Design tokens used | 0 | 16 |
| Hardcoded px | 2 | 0 |
The 96.2% is close to tautological — the baseline writes no UX4G names at all,
so 0% is guaranteed. The number that matters is zero invented names. See
evals/RESULTS.md, including the caveats: n=1, and the scorer was corrected
mid-run.
.mcp.json in the project root:
{
"mcpServers": {
"ux4g": { "type": "http", "url": "https://mcp.ux4g.gov.in/mcp" }
}
}
.cursor/mcp.json:
{
"mcpServers": {
"ux4g": { "url": "https://mcp.ux4g.gov.in/mcp" }
}
}
.vscode/mcp.json:
{
"servers": {
"ux4g": { "type": "http", "url": "https://mcp.ux4g.gov.in/mcp" }
}
}
.kiro/settings/mcp.json in the project, or ~/.kiro/settings/mcp.json for
every project:
{
"mcpServers": {
"ux4g": {
"command": "npx",
"args": ["-y", "mcp-remote@latest", "https://mcp.ux4g.gov.in/mcp", "--transport", "http-only"],
"disabled": false,
"autoApprove": ["ux4g_overview", "ux4g_search", "ux4g_get_component", "ux4g_get_token", "ux4g_get_install", "ux4g_list_versions"]
}
}
}
autoApprove is safe here — every tool is a read-only lookup with no side
effects. Without it Kiro asks before each call, which gets tiring fast.
~/.gemini/antigravity-ide/mcp_config.json, or the MCP section of the IDE's
settings UI:
{
"mcpServers": {
"ux4g": {
"command": "npx",
"args": ["-y", "mcp-remote@latest", "https://mcp.ux4g.gov.in/mcp", "--transport", "http-only"]
}
}
}
If your build offers a direct URL field for remote servers, use
https://mcp.ux4g.gov.in/mcp and skip the command form.
mcp-remote for these twoClaude Code, Cursor and VS Code connect to an HTTP MCP server directly. Not
every client does yet. mcp-remote is a small bridge that speaks stdio to the
editor and HTTP to us, so the same endpoint works everywhere. It needs Node
installed and downloads on first use.
Verified working against this endpoint — it returns all six tools and real data, identical to a direct connection.
Streamable HTTP, POST only. No authentication — the index is public,
read-only data. The server is stateless: every request is self-contained, so
there is no session to establish and no sticky-routing requirement. A bare
curl works, exactly as below.
Opening the endpoint in a browser gives you a short page explaining that, rather than a JSON-RPC error.
curl -X POST https://mcp.ux4g.gov.in/mcp \
-H 'content-type: application/json' \
-H 'accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
skill/SKILL.md in this repo tells an agent when to call which tool and what
to do when something is not found. Copy it into the project (Claude Code:
.claude/skills/ux4g/SKILL.md). Without it the tools still work, but the agent
has to work out the call order itself.
Yes, that is normal. MCP defines two transports, and a hosted server is always an HTTP endpoint — there is no other way to reach one over a network.
What makes it MCP rather than a REST API is the protocol on top: JSON-RPC with
initialize, tools/list and tools/call, driven by your editor. There are no
REST resources to browse and no URL per component, which is why opening /mcp
in a browser shows an explanation instead of data.
You never call it by hand. You put the URL in your editor's config and ask the agent for UI.
stdio — the editor runs the server itself. It spawns the server as a child process and talks over stdin/stdout. No network, no URL, no port.
┌─────────┐ spawns ┌───────────────┐
│ Editor │ ──────────▶ │ node stdio.ts │
│ │ ◀─stdin/────│ your machine │
└─────────┘ stdout └───────────────┘
The process lives and dies with the editor session. Everyone runs their own copy, so everyone needs the code and the 19 MB index locally, and everyone has to update when it changes.
Streamable HTTP — the server runs somewhere, everyone connects. Editors POST JSON-RPC to a URL.
┌─────────┐ ┌──────────────────┐
│ Editor │ ──POST /mcp─────▶ │ dev-mcp-ux4g │
│ Editor │ ──POST /mcp─────▶ │ .negd.in │
│ Editor │ ──POST /mcp─────▶ │ one deployment │
└─────────┘ └──────────────────┘
Same tool code either way. Only the transport differs.
| stdio | HTTP | |
|---|---|---|
| Setup per person | install the package | paste a URL |
| Updates | everyone re-installs | redeploy once |
| Works offline | yes | no |
| Infrastructure | none | you host it |
| Latency | instant | network |
| Usage visibility | none | the miss log |
The index will be wrong sometimes — we have already found 88 classes that the design system's own documentation references and no CSS defines. When one is fixed, a hosted server means the correction reaches everyone on the next request. With stdio it would sit in a package waiting for people to upgrade, and some never would.
The cost is infrastructure to run. For a design system, where the index is the product and it changes, that trade is worth it.
Streamable HTTP has two modes, and serverless hosting forces the choice.
Stateful keeps a session per client, tracked by an Mcp-Session-Id header,
with transports held in memory.
Stateless treats every request as self-contained. That is what this
deployment uses, and the reason is worth knowing if you ever host it yourself:
the server runs as several container tasks behind a load balancer, so a client
that sends initialize to one task and its next request to another would be
told "Bad Request: Server not initialized" — intermittently, depending on how
the request was routed. Statelessness removes the need for sticky routing
entirely.
Nothing is lost by it. Every ux4g_* tool is a pure read of a committed index,
so there is no per-session state worth keeping, and a bare curl -X POST works
without a handshake.
One visible consequence: GET /mcp returns 405. Stateful mode supports a GET
event stream for server-initiated messages; stateless does not. That is why a
browser visiting the endpoint gets a short explanation rather than data.
Some clients only speak stdio. mcp-remote sits between them and an HTTP
server:
┌─────────┐ stdio ┌────────────┐ HTTP ┌──────────────┐
│ Kiro │ ──────▶ │ mcp-remote │ ─────▶ │ ux4g-mcp │
└─────────┘ └────────────┘ └──────────────┘
That is what the Kiro and Antigravity configs above use. Same six tools, same data — verified to return identical results to a direct connection.
Use it whenever you are writing UI for an Indian government service — a portal, a citizen app, a departmental dashboard — and specifically before writing markup for a button, input, form, card, modal, navigation, status tracker, or any Aadhaar / PAN / OTP flow.
It is most valuable where a model is most confidently wrong:
ux4g-otp,
Ux4gAadhaarInputField, progress-sla-indicator or the biometric flow.You do not need it for non-UI code, or a project that does not use UX4G.
| Tool | Use |
|---|---|
ux4g_overview |
What exists. Call once per session before writing UI. |
ux4g_search |
Find something by your own words — "dropdown", "snackbar", "aadhaar field". Never returns nothing. |
ux4g_get_component |
Exact classes (web) or widget and constructor (Flutter), plus a copy-ready snippet. Takes a kind — see below. |
ux4g_get_token |
A CSS custom property with both light and dark values. Pass layer: "semantic" for the themed ones. |
ux4g_get_install |
Exact pinned package and CDN versions, plus the setup the stylesheet import does not cover. |
ux4g_list_versions |
Supported releases and their published package versions. |
Serving 3.3.2 only. 57 components, 4 layout groups, 37 utility groups, 66 patterns, 1,308 tokens.
3.2.0 was retired on 2026-10-05, and 3.3.0 on 2026-10-07. Asking for a retired
release returns a refusal rather than 3.3.2 data under the old label. For 3.2.0 the
refusal carries the rename table — 55 classes changed name between the two releases
and 47 were removed — exactly the silent breakage CLAUDE.md rule #5 is meant to
prevent: ux4g-btn-md renders nothing at 3.3.0 and raises no error anywhere. The 3.3.0 → 3.3.2
upgrade is the opposite: additive, nothing renamed, 31 sizing utilities added, and
the only removals are two tokens (--ux4g-rgb-black/-white) — so its refusal says
exactly that.
ux4g_get_component retrieves four different things, selected by kind.
ux4g_search tells you which kind each result is — pass it back, or the id will
not resolve.
| kind | what it holds | when to reach for it |
|---|---|---|
component (default) |
one UI element | a button, input, card, modal |
layout |
containers, two 12-column grids, responsive breakpoints | first, for any page |
utility |
a class group — spacing, typescale, flex, position |
text sizes, margins, alignment |
pattern |
a whole government journey, stage by stage | sign-in, grievance tracking, document upload |
Two of these are worth knowing about before you start:
Start with kind: "layout". UX4G has its own containers and two separate
12-column grid systems — grid-system (CSS Grid) and flex-grid-system
(Flexbox). They are not interchangeable, and a hand-rolled grid inside a UX4G
page is the most common reason a layout breaks while every class name in it is
correct.
There are 66 patterns. If the task is a recognisable government journey, there is probably a pattern for it: 18 variants cover Identity & Access alone (Sign In, Aadhaar Authentication, OTP Verification, Forgot Password, Auth Error & Lockout, Session Timeout). Each one lists its stages.
include_full: true returns the complete record instead of the budgeted
summary: every extracted snippet, the full class list, all pattern stages. Use
it when a response says the snippet was too large, or when you need exact
nesting for a structural component — footer, app-header and card have full
page skeletons that do not fit a normal response.
layer: "semantic" on ux4g_get_token. UX4G has 617 primitive and 681
semantic tokens. Primitives are the raw palette and are identical in light and
dark by design, so building on one hardcodes a theme. The semantic layer is the
one that moves.
framework is a required enum on ux4g_get_component and ux4g_get_install
with no default. There are four values — html, react, angular, flutter
— advertised by ux4g_overview, and the schema rejects a call that omits it or
passes anything else ('vue' is an error, not a fallback).
The agent decides it; the server takes it at face value and cannot check it.
Pass 'react' in an Angular project and you get className markup back with no
complaint. That is deliberate — the server is a hosted container with no sight
of your repo, so the argument is the only thing it can go on.
ux4g_search needs no framework. Names are shared across the web frameworks and
with Flutter, so you search once and only branch when you fetch.
Once you fetch, the server works in this order:
available_in gate. If the component is not implemented for the
framework you asked for, you get found: true with
available_in_requested_framework: false and an instruction not to
substitute — not a different framework's markup. At 3.3.2, 46 of the 64
components are in all four frameworks, 16 are web-only, and 2 are
Flutter-only (biometric and bottom-sheet).flutter reads the Flutter binding; html,
react and angular all read the same web binding.So the cost of a wrong framework is uneven. html versus angular is free —
the output is identical. react is a mechanical HTML-attribute to
JSX-attribute rewrite — class becomes className, and for becomes
htmlFor on labels — with no structural or class-name difference. Web versus
Flutter is total: different bindings, different names, a different API.
ux4g_get_install splits only web versus Flutter. All three web frameworks get
the same CDN URLs, the same npm pin and the same icon-font prerequisite; only
Flutter gets the pub.dev package instead.
Paste any ux4g- class into ux4g_search and it tells you what defines it:
ux4g_search("ux4g-body-l-strong")
-> defined: true, utility group "typescale"
ux4g_search("ux4g-tag-m")
-> not defined at this version; it will render unstyled. Do not use it.
Useful when reviewing an existing page, and the second case matters: that class appears in the design system's own generated documentation and no stylesheet defines it.
Ask an agent, with the server connected:
Build an OTP verification screen for a government portal. Six digits, with a resend timer and an error state.
A correct run calls ux4g_overview, then ux4g_get_component, and writes
markup using ux4g-otp, ux4g-otp-group, data-ux-otp, data-ux-state and
the real ARIA attributes. If you get form-control and d-flex, the client
did not connect — check your config, not the prompt.
Three more worth trying, because each exercises a different guarantee:
Add a medium primary button. The project pins UX4G 3.2.0.
Must refuse and say 3.2.0 is retired, naming ux4g-btn-m as the 3.3.2
equivalent of ux4g-btn-md. An agent that answers this with 3.3.2 classes under
a 3.2.0 label produces markup that renders unstyled — exactly the failure
version discipline is meant to catch.
Build a face-liveness verification flow for a web portal.
Correct answer is "UX4G implements this for Flutter only." Reporting a gap is harder than filling it, and it is what stops a department shipping something that looks official and is not.
Style a card surface using the design system's colours.
Must use var(--ux4g-*), never a hex value.
ux4g_search, or pass
include_full: true for the complete list.footer, card, app-header, combobox, feedback, file-upload,
sidebar, stepper, time-slot) — call again with include_full: true and
you get them verbatim. Four (alert, toast, popover, spinner) have
examples that use none of their own classes: every published alert example
is a toast trigger button, so offering one would misrepresent the component.
One (social-link) has no published example at all. Classes and variants
are exact in every case.select ships an example
using 4 of its classes because the one using 15 is 15 KB. The note says so,
and include_full: true gets it.ux4g-dropdown-selection and
ux4g-dropdown-single ship on the CDN but not in the npm bundle, at 2.1.0,
3.0.0, 3.0.1 and now the served 3.0.2 — four consecutive releases.
ux4g_list_versions reports this.Two things are not discoverable from a class list, and ux4g_get_install
returns both.
Icons are a ligature font. The glyph name goes in the element's text content:
<span class="ux4g-icon-outlined">search</span> <!-- a magnifier -->
<i class="ux4g-icon-outlined"></i> <!-- nothing, silently -->
The second form is what most people write, coming from Font Awesome or Bootstrap Icons. It is correctly classed, correctly sized, and empty. The fonts ship inside the package and the CDN bundle, so no Google Fonts link is needed — but an npm consumer whose bundler does not copy font assets gets empty boxes with no CSS error.
Text sizes come from typescale, not from free-form font sizes:
ux4g_get_component("typescale", "html", kind: "utility").
The index is generated from pinned commits of the design-system repos and
verified against the live CDN, npm and pub.dev on every CI run. If a class name
looks wrong, it is far more likely that the design system's own docs are
wrong than that the index is — we found 88 undefined classes that way. See
docs/UPSTREAM-FINDINGS.md.
Report anything the server could not resolve. Searches that find nothing are the most valuable output it produces — a direct list of what departments need and UX4G does not yet have.
Staging, for testing. Not production:
mcp.ux4g.gov.in does not resolve;
use staging until it is announced.npm run smoke -- <url>. It calls tools that must
read six different files from the index, because /healthcheck and
tools/list both answer without touching it and will pass on an image that
shipped without one.