← UX4G MCP

Using the UX4G MCP server

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.

Environments

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.


Why it exists

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.


Connecting

Claude Code

.mcp.json in the project root:

{
  "mcpServers": {
    "ux4g": { "type": "http", "url": "https://mcp.ux4g.gov.in/mcp" }
  }
}

Cursor

.cursor/mcp.json:

{
  "mcpServers": {
    "ux4g": { "url": "https://mcp.ux4g.gov.in/mcp" }
  }
}

VS Code (Copilot agent mode)

.vscode/mcp.json:

{
  "servers": {
    "ux4g": { "type": "http", "url": "https://mcp.ux4g.gov.in/mcp" }
  }
}

Kiro

.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.

Antigravity

~/.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.

Why mcp-remote for these two

Claude 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.

Anything else that speaks MCP

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":{}}'

Add the skill too

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.


"Is this a REST API? Is that normal for MCP?"

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.

The two transports

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

Why this one is hosted

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.

Stateful and stateless HTTP

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.

Bridging the two

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.

When to use it

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:

You do not need it for non-UI code, or a project that does not use UX4G.


The six tools

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.

The four kinds

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.

Two parameters that matter

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.

Which framework, and who decides

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:

  1. The 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).
  2. A two-way binding split. flutter reads the Flutter binding; html, react and angular all read the same web binding.
  3. A snippet projection. The web binding stores the snippet in three forms; the response returns the one you asked for, not all three.

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.

Asking what a class is

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.


What good looks like

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.


What it will not do

Known gaps, so they are not surprises


Prerequisites the stylesheet import does not cover

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").


If something looks wrong

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.


Status

Staging, for testing. Not production: