Build a real private MCP marketplace UX across catalog, governance, install, access, and publish flows

## Summary

MCP Runtime already has the foundations for a private MCP platform:

- `MCPServer` resources and operator-managed deployment
- gateway / policy / grants / sessions
- Sentinel analytics, audit, UI, and API surfaces
- tenant/admin platform direction in the docs and marketing site

But the current shipped product is still much closer to an operator/governance dashboard than a true private MCP marketplace.

This issue is an umbrella for turning the current platform into the marketplace-style governed MCP experience that the docs and website already imply.

## Why this issue exists

After reviewing:

- the live cluster state
- the current website / product UI
- the docs
- the platform management APIs
- existing issues

there is a clear gap between:

1. **what MCP Runtime says it is**
2. **what the current UI/API make possible**

The website already says:

- the public entrypoint shows a "marketplace-style experience"
- companies can deploy that same platform model privately

But the current product UI is still mostly:

- flat MCP server cards
- raw `access_json`
- admin governance forms
- operations tabs
- no real catalog search/facets
- no server detail model
- no governed playground
- no user access-request UX
- no MCPServer-native publish flow in-product

## Related issues already on file

These issues overlap with parts of the end-state and should be treated as related building blocks:

- [#94](https://github.com/Agent-Hellboy/mcp-runtime/issues/94) MCPServer can report gateway ready while mcp-proxy sidecar is not present in the live Deployment
- [#90](https://github.com/Agent-Hellboy/mcp-runtime/issues/90) feat(operator): add platform readiness gate for MCPServer traffic
- [#88](https://github.com/Agent-Hellboy/mcp-runtime/issues/88) feat(api): add tenant namespace provisioning and scoped MCPServer deploys
- [#76](https://github.com/Agent-Hellboy/mcp-runtime/issues/76) Improve admin operations page for user activity, logins, image publishing, and platform actions
- [#75](https://github.com/Agent-Hellboy/mcp-runtime/issues/75) Add tenant analytics page for MCP servers deployed by that tenant
- [#74](https://github.com/Agent-Hellboy/mcp-runtime/issues/74) Require CLI + API key for image publish and deploy to the public platform
- [#73](https://github.com/Agent-Hellboy/mcp-runtime/issues/73) Add configurable per-server push rate limiting with admin-controlled window
- [#59](https://github.com/Agent-Hellboy/mcp-runtime/issues/59) Add role-based UI login for admin and user access
- [#14](https://github.com/Agent-Hellboy/mcp-runtime/issues/14) Add admin vs tenet workflow

This issue is **not** meant to replace those. It is meant to define the broader product shape and track the missing UX/API work around them.

## Proposed product direction

### 1. Improve first-screen marketplace copy

The first screen should describe what the platform actually does.

Suggested direction:

> Discover governed MCP servers
> Search approved tools by team, trust level, transport, auth mode, and deployment health.

Why:

- Current in-product copy is too generic.
- The marketing/docs copy is already more ambitious than the shipped UI.
- The product differentiator is governed MCP discovery and access, not generic infrastructure monitoring.

### 2. Add real catalog search and facets

The current server listing is a flat grid with no marketplace search/filter surface.

Add search and facets for at least:

- owner / team
- namespace / environment
- ready / degraded / unknown status
- gateway enabled
- policy mode
- auth mode
- required trust
- tool / resource / prompt / task inventory
- access available / request required
- published by / tenant scope where relevant

Notes:

- Some of these fields are not returned by the current runtime server payload and will require API enrichment.
- Search/faceting should work for both shared catalog (`mcp-servers`) and tenant-scoped views.

### 3. Make governance visible on server cards

Server cards should surface governance and product-relevant metadata, not just name + namespace + raw inventory.

Target card surface:

- approval badge such as `Approved`, `Restricted`, `Observe only`, `Experimental`, `Deprecated`
- required trust level
- auth mode
- gateway readiness
- policy readiness
- last deploy age
- tool count
- owner / namespace / team
- primary CTA such as:
- `Open details`
- `Use via broker`
- `Request access`

This is especially important because current cluster state can be misleading without better governance/status surfacing, as captured in #94 and #90.

### 4. Create a real server detail page

A flat card is not enough.

Suggested server detail information architecture:

- `Overview`
- `Tools`
- `Install`
- `Access`
- `Security`
- `Usage`
- `Audit`

Why:

- Access, Security, and Audit are the product, not back-office implementation details.
- These should not be hidden behind admin-only pages.
- The detail page should unify:
- endpoint / route info
- inventory
- gateway / policy / auth state
- trust requirements
- usage analytics
- recent audit and decision history
- access pathways

### 5. Replace raw access JSON with client-specific install snippets

Current UI behavior is to render `access_json` directly.

Keep that underlying data, but wrap it in a real install UX:

- client selector
- copy button
- validation state
- endpoint reachability check
- auth/access warning
- broker-required vs direct-path explanation

Starting client targets:

- Claude Desktop
- Cursor
- VS Code
- Windsurf
- Docker Gateway
- generic MCP JSON

If the gateway/policy model changes install behavior, the install page should say so explicitly.

### 6. Build a governed playground

The winning product surface is not “try a tool” in isolation.

The winning surface is “see the governed request path.”

Playground should show:

- selected server / tool
- structured input form
- brokered execution result
- policy decision
- matched grant / session
- emitted audit event
- latency / status
- effective trust where relevant

This turns MCP Runtime into a product that demonstrates governance rather than assuming users infer it from docs.

### 7. Add end-user access request UX

Today admins can create grants and sessions, but the user-side marketplace flow is missing.

Target restricted-server flow:

1. user opens restricted server
2. user sees why access is restricted
3. user sees owner / team / namespace
4. user requests time-bound access
5. admin approves into `MCPAccessGrant` / `MCPAgentSession`
6. user sees request status and can retry/use when approved

This likely depends on role/scoped-user work from #59 and broader tenant/admin modeling from #14 and #88.

### 8. Add MCPServer-native publish flow

A private marketplace needs supply-side UX, not just deploy plumbing.

Target publish flow:

- upload or edit `MCPServer` manifest
- validate image and route
- declare tools / prompts / resources / tasks
- choose gateway / policy preset
- preview install endpoint
- preview access/security posture
- publish into catalog

This should build on the platform-controlled publish/deploy work in #74 and #88, rather than exposing raw Deployment-only mechanics.

## Cluster, docs, and product reality that motivate this

From the current state review:

- The live cluster has the platform pieces running, but analytics are empty (`mcp.events` row count is `0`).
- The current UI is a basic dashboard with tabs, not a marketplace product.
- The docs and website already promise a stronger platform/marketplace shape than the shipped UX currently provides.
- The runtime API currently returns only a limited `serverInfo` model and a raw `access_json` block, which is not enough for the desired marketplace UX.

## Suggested implementation tracks

This is large enough that it should probably be decomposed into epics/sub-issues such as:

### Track A: Catalog foundation

- enrich runtime server payloads with governance, owner, trust, auth, gateway, policy, and deployment metadata
- add search + facets
- add richer server cards

### Track B: Server detail and install UX

- add server detail page
- add install snippets by client
- add validation/reachability states

### Track C: Governed execution UX

- add governed playground
- show policy decision + grant/session + audit linkage

### Track D: Access workflow

- role-aware user catalog view
- end-user access request flow
- admin approval surfaces tied to grants/sessions

### Track E: Publish workflow

- MCPServer-native publish/edit/publish UX
- validation and preview
- tenant-scoped/server-scoped supply-side publishing

### Track F: Status and trustworthiness

- fix incorrect gateway/policy readiness signals (#94)
- add stronger platform readiness semantics (#90)
- ensure catalog status reflects real server state

## Acceptance criteria for this umbrella

This umbrella can be considered complete when MCP Runtime offers a credible private MCP marketplace experience with:

- a first screen centered on governed server discovery
- searchable/faceted catalog experience
- server cards that expose trust/governance state
- a dedicated server detail model
- client-specific install snippets instead of raw JSON
- a governed playground that demonstrates the request path
- end-user access request UX for restricted servers
- a first-class MCPServer publish flow
- linkage to analytics/audit surfaces that reflect real runtime state

## Non-goals

This issue does **not** require everything to land in one PR.

The goal is to establish a clear product target and connect the already-open platform issues to a cohesive marketplace roadmap.

## Suggested follow-up

After creating this umbrella, open focused child issues for the currently untracked areas:

- marketplace search + facets
- server card governance badges / CTAs
- server detail page
- client-specific install snippets
- governed playground
- end-user access request UX
- MCPServer publish UX