Proposal: JSON-LD Web Markup for MCP App Discovery #606

yannj-fr · 2026-04-09T06:36:30Z

yannj-fr
Apr 9, 2026

Pre-submission Checklist

I have verified this would not be more appropriate as a feature request in a specific repository
I have searched existing discussions to avoid duplicates

Your Idea

Related:

Disclaimer

This discussion could also be brought more generically to broadcast any MCP server from a website (without colliding with WebMCP).

Problem Statement

MCP Apps (ext-apps) bring interactive UIs to AI conversations -a streaming service can surface a video player, an e-commerce site can render a checkout form, a data platform can display a live dashboard. The extension is now supported by Claude, ChatGPT, VS Code Copilot, Goose, Postman, and others.

But discovery is still a blind spot. When an MCP-capable platform crawls or cites a website, it has no way to know that the site publishes an MCP App. The platform would need to speculatively probe /.well-known/mcp.json on every visited domain, which is impractical. And even if it found the server, it wouldn't know the server exposes interactive ui:// resources -that information is only available after connecting and inspecting tool metadata.

Concrete example: M6+ (m6plus.fr), a French streaming platform, publishes an MCP App that lets users search the catalog, view program details, and get personalized recommendations -all rendered as rich UI inside the conversation. M6+ also lists this app on specific platforms:

ChatGPT: https://chatgpt.com/apps/m6plus/asdk_app_69b7c7a99cd88191b6f7e938c1ab78dc
Claude: https://claude.ai/connectors/m6plus (hypothetical)

Today, none of these facts are machine-discoverable from m6plus.fr itself. A user browsing the M6+ website through an MCP-capable agent gets no signal that a richer, interactive integration exists.

Proposed Solution

A JSON-LD vocabulary that website owners embed in their HTML <head> to declare:

"We have an MCP App" -the MCP endpoint URL, app name, description, capabilities.
"Here's where to find it on specific platforms" (optional) -direct links to the app's listing on ChatGPT, Claude, or any other host that has its own catalog.

This leverages a format that every major crawler already parses (92% of AI and commercial crawlers attempt JSON-LD first, per the W3C Crawler Transparency Report). No new protocol to support -just structured metadata in a place crawlers already look.

How it fits the ecosystem

Mechanism	What it answers
`.well-known/mcp.json` (SEP-1649)	"What can this MCP server do?" (capabilities, transport)
MCP Registry	"Which MCP servers exist?" (centralized catalog)
`ext-apps` spec (`ui://` scheme)	"How does this app render UI?" (protocol-level)
JSON-LD in HTML (this proposal)	"Does this website have an MCP App, and where can I use it?"

JSON-LD Schema

Context

https://modelcontextprotocol.io/schemas/app-discovery/v1

Minimal Example

The absolute minimum -"this site has an MCP App":

<script type="application/ld+json">
{
  "@context": [
    "https://schema.org",
    {
      "mcp": "https://modelcontextprotocol.io/schemas/app-discovery/v1#"
    }
  ],
  "@type": "WebSite",
  "url": "https://www.m6plus.fr",
  "mcp:app": {
    "@type": "mcp:MCPApp",
    "mcp:endpointUrl": "https://prod.mcp.m6plus.fr/mcp"
  }
}
</script>

Three lines of meaningful data. An MCP client parsing this page now knows exactly where to connect.

Extended Example

Rich metadata for display, pre-filtering, and platform deep-linking:

<script type="application/ld+json">
{
  "@context": [
    "https://schema.org",
    {
      "mcp": "https://modelcontextprotocol.io/schemas/app-discovery/v1#"
    }
  ],
  "@type": "WebSite",
  "name": "M6+",
  "url": "https://www.m6plus.fr",
  "mcp:app": {
    "@type": "mcp:MCPApp",
    "mcp:name": "M6+",
    "mcp:description": "Search the M6+ catalog, browse programs, get personalized recommendations and check streaming availability -with a rich interactive UI.",
    "mcp:endpointUrl": "https://prod.mcp.m6plus.fr/mcp",
    "mcp:protocolVersion": "2025-11-25",
    "mcp:extensionId": "io.modelcontextprotocol/ui",
    "mcp:serverCardUrl": "https://www.m6plus.fr/.well-known/mcp.json",
    "mcp:iconUrl": "https://www.m6plus.fr/assets/mcp-app-icon.png",
    "mcp:platformLinks": [
      {
        "@type": "mcp:PlatformLink",
        "mcp:platform": "chatgpt",
        "mcp:url": "https://chatgpt.com/apps/m6plus/asdk_app_69b7c7a99cd88191b6f7e938c1ab78dc"
      },
      {
        "@type": "mcp:PlatformLink",
        "mcp:platform": "claude",
        "mcp:url": "https://claude.ai/connectors/m6plus"
      }
    ],
    "mcp:status": "active"
  }
}
</script>

Multiple Apps

A site exposing several MCP Apps (e.g., a public catalog browser and a subscriber-only player):

<script type="application/ld+json">
{
  "@context": [
    "https://schema.org",
    {
      "mcp": "https://modelcontextprotocol.io/schemas/app-discovery/v1#"
    }
  ],
  "@type": "WebSite",
  "name": "M6+",
  "url": "https://www.m6plus.fr",
  "mcp:apps": [
    {
      "@type": "mcp:MCPApp",
      "mcp:name": "M6+ Catalog",
      "mcp:description": "Browse the M6+ catalog and check availability. No account needed.",
      "mcp:endpointUrl": "https://mcp.m6plus.fr/public/v1",
      "mcp:extensionId": "io.modelcontextprotocol/ui",
      "mcp:platformLinks": [
        {
          "@type": "mcp:PlatformLink",
          "mcp:platform": "chatgpt",
          "mcp:url": "https://chatgpt.com/apps/m6plus/asdk_app_69b7c7a99cd88191b6f7e938c1ab78dc"
        }
      ]
    },
    {
      "@type": "mcp:MCPApp",
      "mcp:name": "M6+ Player",
      "mcp:description": "Watch M6+ content, manage your watchlist and get personal recommendations.",
      "mcp:endpointUrl": "https://prod.mcp.m6plus.fr/mcp",
      "mcp:extensionId": "io.modelcontextprotocol/ui"
    }
  ]
}
</script>

Schema Definition

`mcp:MCPApp`

Property	Type	Required	Description
`mcp:endpointUrl`	`URL`	Yes	The MCP server endpoint serving this app
`mcp:name`	`string`	Recommended	Human-readable app name
`mcp:description`	`string`	Recommended	What the app does, for users and crawlers
`mcp:extensionId`	`string`	Recommended	MCP extension identifier, `io.modelcontextprotocol/ui` for apps
`mcp:protocolVersion`	`string`	Recommended	MCP protocol version (e.g., `2025-11-25`)
`mcp:serverCardUrl`	`URL`	Recommended	URL to `.well-known/mcp.json` for full server details
`mcp:platformLinks`	`mcp:PlatformLink[]`	Optional	Links to platform-specific app listings
`mcp:iconUrl`	`URL`	Optional	App icon
`mcp:documentationUrl`	`URL`	Optional	Developer docs
`mcp:status`	`string`	Optional	`active`, `beta`, `deprecated`
`mcp:datePublished`	`Date`	Optional	First publication date

`mcp:PlatformLink`

Links to the app's listing on specific AI platforms. This is purely informational -it tells crawlers and users where this app is already available, enabling deep-linking into platform-specific install flows.

Property	Type	Required	Description
`mcp:platform`	`string`	Yes	Platform identifier (see registry below)
`mcp:url`	`URL`	Yes	Direct URL to the app listing on that platform
`mcp:label`	`string`	Optional	Display label (e.g., "Open in ChatGPT")

Platform identifiers (non-exhaustive, extensible):

`mcp:platform`	Platform	Example URL pattern
`chatgpt`	ChatGPT (OpenAI)	`https://chatgpt.com/apps/{name}/{id}`
`claude`	Claude (Anthropic)	`https://claude.ai/connectors/{name}`
`copilot`	Microsoft Copilot	`https://copilot.microsoft.com/apps/{id}`
`gemini`	Gemini (Google) (hypothetical)	`https://gemini.google.com/extensions/{id}`
`goose`	Goose	-
`vscode`	VS Code / Copilot Chat	`vscode:extension/{publisher}.{name}`

New platforms self-register by choosing an identifier and documenting their URL pattern. No central gatekeeper.

Container Properties (on `schema:WebSite`)

Property	Type	Description
`mcp:app`	`mcp:MCPApp`	Single MCP App declaration
`mcp:apps`	`mcp:MCPApp[]`	Multiple MCP App declarations

Why `mcp:platformLinks`?

MCP is platform-agnostic by design -the same server works with ChatGPT, Claude, Copilot, and any MCP-compatible host. But in practice, each platform has its own app catalog with its own install flow and listing URL.

mcp:platformLinks bridges this gap:

For crawlers: When ChatGPT crawls m6plus.fr and finds a mcp:PlatformLink with "mcp:platform": "chatgpt", it can directly link the user to the install page instead of asking them to configure a raw MCP endpoint. Same logic for Claude, Copilot, etc.

For users: A human reading the JSON-LD (or a directory built from it) immediately sees where the app is available and can click through to their preferred platform.

For app developers: A single JSON-LD block replaces the need to maintain separate discovery mechanisms for each platform. Update the markup once, all crawlers pick it up.

The field is optional -a site can declare mcp:endpointUrl only, and any MCP client can connect directly. Platform links are a convenience layer, not a requirement.

Use Cases

1. Opportunistic Discovery During Browsing

An MCP client (Claude, ChatGPT with browse, a browser extension) visits m6plus.fr/shows/top-chef. It parses the JSON-LD, discovers the MCP App, and surfaces a contextual prompt: "M6+ has an interactive app -search the catalog and get recommendations directly here?" If the user accepts, the client connects to mcp:endpointUrl and the ui:// resources render inline.

2. Platform-Aware Deep Linking

ChatGPT crawls m6plus.fr and finds its own platform link in mcp:platformLinks. When citing M6+ content, it can say: "M6+ is also available as a ChatGPT app -open it here". The user gets a one-click install path instead of a raw endpoint URL.

3. Cross-Platform App Directory

A third-party service crawls the web for mcp:MCPApp JSON-LD entries and builds a universal MCP App directory -showing, for each app, which platforms it's listed on (via mcp:platformLinks) and the raw MCP endpoint for direct connection. This is the missing "Yellow Pages" for MCP Apps.

4. Registry Enrichment

The MCP Registry crawls JSON-LD as a complementary discovery signal. When a new mcp:MCPApp entry is found on a domain not yet in the registry, it's flagged for automatic indexing. Platform links provide additional metadata the registry can surface (e.g., "also available on ChatGPT").

5. SEO for AI

Just as schema.org markup helps websites appear in rich search results, mcp:MCPApp markup helps apps appear in AI agent recommendations. A site that declares its MCP App in JSON-LD is more likely to be recommended for interactive use by agents that parse structured data during retrieval.

Security Considerations

Domain alignment. mcp:endpointUrl must share the same registrable domain as the page serving the JSON-LD (or be explicitly authorized via CORS/DNS). A page on example.com cannot advertise an MCP App at evil.com.

Platform link validation. Crawlers should verify that mcp:PlatformLink URLs actually resolve and point to a legitimate app listing. A link to chatgpt.com/apps/... that 404s or redirects to a phishing page should be ignored.

Public metadata only. No secrets in markup -ever. Auth details are limited to the type of scheme and the public authorization URL. Credentials flow through the MCP protocol's own auth mechanisms.

Spoofing. A malicious site could embed JSON-LD with "mcp:name": "Netflix" on an unrelated domain. Clients must display the actual domain of the endpoint, not the self-declared name, when prompting users to connect. The mcp:platformLinks offer some defense here: a legitimate app will have valid platform listings, a spoofed one won't.

Implementation Path

Publish the JSON-LD context at modelcontextprotocol.io/schemas/app-discovery/v1 with the vocabulary and a validating JSON Schema.
Document it alongside ext-apps. Add a "Web Discovery" section to the MCP Apps documentation, with copy-paste JSON-LD snippets and integration guidance.
Add ui to the capabilities vocabulary. The current MCP spec defines tools, resources, and prompts. Apps need ui as a first-class capability signal so crawlers can distinguish apps from headless servers without connecting.
Pilot with early adopters. Work with sites already deploying MCP Apps (M6+, etc.) to add JSON-LD and measure discovery rates.
Add JSON-LD parsing to MCP client SDKs. The TypeScript and Python ext-apps SDKs could include a utility to extract mcp:MCPApp entries from HTML -making opportunistic discovery trivial for client authors.
Platform link registry. Maintain a lightweight list of known mcp:platform identifiers and their URL patterns, either in the spec or as a community-maintained file in the ext-apps repo.

Open Questions

Should mcp:platformLinks use a closed or open platform registry? The current proposal uses an open set of string identifiers. An alternative: require platforms to register their identifier and URL pattern in a YAML/JSON file in the ext-apps repo, similar to IANA media type registration.
Page-level vs. site-level placement. Should JSON-LD appear only on the homepage, or can it be page-specific? A product page could declare an app scoped to that product category, but this adds complexity.
<link> tag shorthand. For the minimal case (one app, one endpoint), a <link rel="mcp-app" href="https://mcp.m6plus.fr/v1"> is simpler than a full JSON-LD block. Define both?
Multi-tenant platforms. Shopify, Wix, etc. host millions of sites. Should tenants embed per-store JSON-LD pointing to a shared multi-tenant MCP App, or should the platform declare a single app with a tenant routing mechanism?
Relationship to OpenAI Apps SDK. OpenAI's Apps SDK now supports MCP as a first-class integration path. Should mcp:platformLinks for chatgpt point to the Apps SDK listing, the ChatGPT app store URL, or both?

Summary

MCP Apps are the interactive frontier of MCP -but they're invisible to the web. This proposal adds a single JSON-LD block to fix that:

mcp:MCPApp declares the app exists and where to connect.
mcp:platformLinks (optional) tells crawlers where the app is already listed, per platform.

The format is JSON-LD because crawlers already parse it. The vocabulary is MCP-namespaced because it's MCP-specific. The platform links are optional because MCP is platform-agnostic -but pragmatically, users want one-click install, not raw endpoint URLs.

We're looking for feedback on the schema, the platform link model, and the right level of detail for the JSON-LD payload.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Proposal: JSON-LD Web Markup for MCP App Discovery #606

Uh oh!

{{title}}

Uh oh!

Replies: 0 comments

Select a reply

Uh oh!

Proposal: JSON-LD Web Markup for MCP App Discovery #606

Uh oh!

yannj-fr Apr 9, 2026

Pre-submission Checklist

Your Idea

Disclaimer

Problem Statement

Proposed Solution

How it fits the ecosystem

JSON-LD Schema

Context

Minimal Example

Extended Example

Multiple Apps

Schema Definition

mcp:MCPApp

mcp:PlatformLink

Container Properties (on schema:WebSite)

Why mcp:platformLinks?

Use Cases

1. Opportunistic Discovery During Browsing

2. Platform-Aware Deep Linking

3. Cross-Platform App Directory

4. Registry Enrichment

5. SEO for AI

Security Considerations

Implementation Path

Open Questions

Summary

Scope

Replies: 0 comments

yannj-fr
Apr 9, 2026

`mcp:MCPApp`

`mcp:PlatformLink`

Container Properties (on `schema:WebSite`)

Why `mcp:platformLinks`?