Build your sign-up app

A sign-up app is deliberately small: one MCP server (a zero-dependency Node 18+ HTTP server is enough — no framework, no build step) plus one self-contained HTML View. The server exposes three tools and calls your existing account-creation and credential endpoints; the View is your card — logo, colors, tagline, fonts — talking to the host over postMessage. If you haven’t read Sign-up MCP Apps yet, start there for the flow and the trust model.

Gravity maintains a complete reference implementation of everything on this page — the server, the View framework with brand packs, a host-side SDK, and a one-command scaffold that emits a runnable branded app. Ask your Gravity contact for access and you can start from a working app instead of a blank file.

Hand it to your agent

Building with Devin, Claude Code, or Cursor? Paste this prompt — it carries everything the agent needs:

Build our company a Gravity sign-up MCP App (an MCP Apps card that lets a
user sign up and collect API keys inside any MCP Apps host).

1. Build a zero-dependency Node 18+ MCP server (JSON-RPC 2.0 over
   Streamable HTTP, POST /mcp) exposing three tools — offer, provision,
   credentials — plus one ui:// resource: a single self-contained HTML View
   served as text/html;profile=mcp-app with a closed CSP (no connect
   domains). Link every tool to the View via _meta.ui.resourceUri.
2. Wire the backend: (a) the provision handler must call our account/key-
   creation API (idempotent per email) and return a one-time
   `credentials_url`, never raw key values; (b) the credentials handler
   redeems that URL from our one-time store (delete-on-read, short TTL,
   same-origin enforced).
3. Brand the View: our real logo as an inline SVG, our exact colors as CSS
   vars with both dark and light variants, tagline, CTA label, and our
   actual fonts embedded as data-URI @font-face rules (the CSP allows no
   network).
4. Enforce the security invariants: consent gating (`user_consent === true`
   from the user's click), Gravity grant verification
   (signature/expiry/slug/search_id, HMAC with our Gravity signing secret),
   one-time link burn, browser-origin POST rejection, and key values never
   in tool text or model context (structuredContent only, app-only
   credentials tool).
5. Test the golden path in a browser against a stubbed backend: card renders
   with our branding (both themes) → email + Sign up → confirmation →
   masked keys → per-key copy and Copy all work while masked →
   click-to-reveal/hide → model context contains key names only.

The Gravity signing secret comes from the Index dashboard (Your products →
Generate signing secret); load it from env, never hard-code it. Full
contract: https://docs.trygravity.ai/gravity-index/build-signup-app

The contract: three tools

Your MCP server exposes exactly three tools, all linked to your ui:// resource via _meta.ui.resourceUri:

Offer tool (model + app)

Returns the recommended service — name, slug, offer data — as structuredContent, plus a useful plain-text fallback for hosts without MCP Apps. When facilitation signing is enabled, the result also carries the short-lived signed grant binding (search_id, slug).

Provision tool (model + app)

Takes user_email, user_consent, grant. Refuses unless user_consent === true (the user’s click on the Sign up button is the consent) and the grant verifies — signature, expiry, slug, and search ID. Calls your normal account-creation API (idempotent per email) and returns a one-time credentials_url — never the key values.

Credentials tool (app-only)

Declared with visibility: ["app"] so the model can never call it. Redeems the one-time URL; the link burns on first read. Values go only in structuredContent, rendered inside the View. The tool’s text — and the model context — carry key names only.

Protocol surface

Your server implements the standard MCP Apps surface:

initialize advertises capabilities.extensions["io.modelcontextprotocol/ui"] with mimeTypes: ["text/html;profile=mcp-app"]
one ui:// resource returns the View with that MIME type and a closed CSP (connectDomains: [] — the card makes zero network requests of its own)
flow tools carry _meta.ui.resourceUri (plus "openai/outputTemplate" for Apps SDK hosts)
every tool result includes a plain-text fallback so non-UI hosts still work

The View: framework + brand pack

Structure the View as two layers so branding never touches the plumbing. The framework layer owns the postMessage bridge (accept messages only from window.parent, lock onto the first origin), the sign-up flow, and the masked key rows. The brand pack is a plain object you swap per brand:

mycompany: {
  logo: '<svg ...>...</svg>',        // your official mark, inline SVG
  vars: {
    "--bg": "#0c0d0d",               // card background
    "--accent": "#00e599",           // CTA button
    "--accent-fg": "#0c0d0d",        // CTA label
    "--font": "'Inter', sans-serif", // your actual typeface
    "--mono": "'Geist Mono', monospace",
  },
  tagline: "Serverless Postgres",
  cta: "Sign up",
  fonts: ["Inter", "Geist Mono"],    // embedded as data URIs at startup
},

Fonts are embedded as data-URI @font-face rules because the card’s CSP allows no network — the user sees your real typography, not a system fallback. What the user should experience: logo + tagline + email + Sign up → spinner → “Account created” → your keys appear in place, masked (••••). Copy — per key or Copy all as .env lines — works while masked; clicking a value reveals it, clicking again hides it. Ship dark and light variants of your brand pack; the card follows the host’s theme.

Wiring your backend

A common question: how does the card in the iframe reach your backend to create the account? It doesn’t — the View has zero network access (its CSP declares no connect domains). Every hop is:

The card sends tools/call over postMessage to the host.
The host proxies the call to your MCP server — the one Node process you deployed.
Your server (server-side, with your secrets) calls your normal account-creation API and returns a one-time credentials_url.
The card redeems that URL through the same bridge via the app-only credentials tool; values render only inside the iframe.

So there are exactly two integration points in your server: the provision handler → your account/key-creation endpoint, and the credentials handler → your one-time credential store (delete-on-read, short TTL). Your API keys live on your server; the browser, the host, and the model never see them.

How hosts render your card

You don’t build anything host-side. An MCP Apps-capable host fetches your ui:// resource, renders it in a sandboxed iframe (sandbox="allow-scripts" — opaque origin), and proxies the View’s tools/call requests back to your MCP server over its own connection. One consequence worth designing for: the browser must never call your MCP server directly — reject requests that carry a browser Origin header and let hosts proxy the JSON-RPC server-side.

Access control

Two layers, both required for a deployed app:

Transport: your MCP server is a protected resource per the MCP authorization spec. Unauthenticated requests get 401 + WWW-Authenticate: Bearer resource_metadata=…; hosts authenticate with OAuth 2.1 (authorization-code + PKCE, audience-bound tokens) and retry.
Facilitation grants: account creation only for Gravity-facilitated flows. Gravity signs a short-lived grant with your account signing secret (generate it in the Index dashboard: Your products → Generate signing secret); your provision tool verifies signature, expiry, slug, and search ID before creating anything. An unfacilitated caller cannot provision.

Plus the always-on invariants: reject browser-origin POSTs, enforce that credentials_url points at your own API, burn one-time links on redeem, and never log credentials or PII.

Steps to ship

Stand up the server

Three tools, one ui:// resource, plain-text fallbacks — the contract above. A single Node 18+ process with no dependencies is enough.

Wire your backend

Point the two integration points at your account-creation and credential endpoints — the same partner/provisioning API you likely already have. Provision must be idempotent per email; credentials one-time and expiring.

Add your brand pack

Logo SVG, CSS vars, tagline, fonts — keep branding in one place, separate from the bridge and flow code.

Keep the security invariants

Consent gating, grant verification, one-time credential redemption, and the value-free model context — non-negotiable for a listed app.

Test locally, then deploy and register

Run the golden path against a stubbed backend: card renders → email + Sign up → confirmation → masked keys → Copy + reveal. Then deploy one Node process and register the endpoint in the Index dashboard: open your product’s configuration, set the Provisioning mode to MCP App, and enter your MCP server URL.

Want your service listed and provisioning-enabled first? Start at For Service Providers.

Start here

Provisioning

Explore

Interfaces

Partners

Build your sign-up app

Hand it to your agent

The contract: three tools

Protocol surface

The View: framework + brand pack

Wiring your backend

How hosts render your card

Access control

Steps to ship

​Hand it to your agent

​The contract: three tools

​Protocol surface

​The View: framework + brand pack

​Wiring your backend

​How hosts render your card

​Access control

​Steps to ship

Hand it to your agent

The contract: three tools

Protocol surface

The View: framework + brand pack

Wiring your backend

How hosts render your card

Access control

Steps to ship