Expand description
Typed MCP Apps registration and resources for rmcp servers.
Start with StaticUiResource for embedded HTML. With the server feature,
AppRouter groups rmcp tools and resources and checks their associations;
AppServer provides the common server handling. With macros, the optional
derive declares fixed views and app_router associates each UI tool with its
view in one place. Manual declarations and routing remain directly usable.
Consumers choose their runtime and transport and own business logic/access checks.
§Simple application (server and macros)
The consumer enables rmcp’s server and macros features. The HTML below is
this project’s bundled example; use a path relative to your own declaring file.
rmcp generates both schemas from the Rust models; no input schema JSON is needed.
use mcp_apps_server::{AppServer, StaticUiResource, app_router};
use rmcp::{tool, schemars::JsonSchema, ServerHandler,
handler::server::wrapper::{Json, Parameters}};
use serde::{Deserialize, Serialize};
#[derive(StaticUiResource)]
#[ui_resource(id = "inventory/dashboard", name = "dashboard",
html_file = "../examples/dashboard.html")]
struct Dashboard;
#[derive(Deserialize, JsonSchema)]
#[schemars(crate = "rmcp::schemars")]
#[serde(deny_unknown_fields)]
struct Input { sku: String }
#[derive(Serialize, JsonSchema)]
#[schemars(crate = "rmcp::schemars")]
struct Snapshot { sku: String, available: u32 }
struct Inventory;
#[app_router]
impl Inventory {
#[tool(description = "Read inventory")]
#[ui(resource = Dashboard)]
fn snapshot(&self, Parameters(input): Parameters<Input>) -> Json<Snapshot> {
Json(Snapshot { sku: input.sku, available: 12 })
}
}
let server = AppServer::new(Inventory, Inventory::app_router()?)?;
assert!(server.get_info().capabilities.resources.is_some());
assert!(server.get_tool("snapshot").is_some());Construction performs no request or transport activity. Call rmcp’s
ServiceExt::serve with the transport you choose when ready to serve. The
repository’s examples/server.rs supplies the complete stdio lifecycle.
§Custom integration
Keep your own ServerHandler when you need authorization middleware, prompts,
unrelated resources or custom lifecycle behavior. Prepare the same router,
call its validation before serving, then delegate with the original request
and context. Its lists are unpaginated; your handler owns filtering, pagination
and selecting other resource owners. Callback errors are not fallback signals.
See AppRouter for executable tool and dynamic-resource examples and
AppServer for the supported ready-server methods. The repository’s
examples/custom_server.rs implements the complete manual equivalent.
Implement your own handler over the same prepared router
This handler replaces the ready adapter. With macros, obtain the same router
from Inventory::app_router(); with manual declarations, register resources
and associate rmcp tools explicitly. Validate the router and
store it with your application state. These methods let you insert access
checks and retain other MCP methods. A fully manual resource declaration is
demonstrated on StaticUiResource.
use mcp_apps_server::{AppRouter, UiResource, UiResourceRoute, UiResourceUri};
use rmcp::{ErrorData, RoleServer, ServerHandler, model::*, service::RequestContext};
struct ExistingServer<S> { state: S, apps: AppRouter<S> }
impl<S: Send + Sync + 'static> ServerHandler for ExistingServer<S> {
fn get_info(&self) -> ServerConfig {
let mut info = ServerConfig::default();
self.apps.declare_capabilities(&mut info.capabilities);
info
}
fn get_tool(&self, name: &str) -> Option<Tool> { self.apps.get_tool(name) }
async fn list_tools(&self, request: Option<PaginatedRequestParams>, _: RequestContext<RoleServer>)
-> Result<ListToolsResult, ErrorData> { self.apps.list_tools(request) }
async fn list_resources(&self, request: Option<PaginatedRequestParams>, _: RequestContext<RoleServer>)
-> Result<ListResourcesResult, ErrorData> { self.apps.list_resources(request) }
async fn call_tool(&self, request: CallToolRequestParams, context: RequestContext<RoleServer>)
-> Result<CallToolResponse, ErrorData> {
// Authorize the original request before delegating.
self.apps.call_tool(&self.state, request, context).await
}
async fn read_resource(&self, request: ReadResourceRequestParams, context: RequestContext<RoleServer>)
-> Result<ReadResourceResponse, ErrorData> {
// Select other resource owners by URI here when needed.
self.apps.read_resource(&self.state, request, context).await
}
}§Low-level declarations
UiResource prepares a descriptor and matching HTML contents. ToolUi
and ResourceUi prepare typed declarations and compose them into open rmcp
metadata, preserving unknown keys. Omitted fields leave existing values intact;
unequal supplied scalar/array values return MetadataError::Conflict without
a partial update. These primitives remain usable without either optional feature.
use mcp_apps_server::{ResourceUi, UiResource, UiResourceUri};
let resource = UiResource::new(UiResourceUri::new("ui://inventory/dashboard")?, "dashboard");
let mut ui = ResourceUi::default();
ui.prefers_border = Some(true);
let contents = resource.html_contents("<!doctype html><html><body>Inventory</body></html>")
.with_meta(ui.to_meta()?);§Capabilities, security and limits
ui_capability inspects caller-supplied client capabilities and distinguishes
absent, malformed and valid non-HTML support. On current rmcp requests use
RequestContext::client_capabilities() rather than assume initialization is
always the source. The consuming application chooses its fallback behavior.
HTML is supplied by the consumer, without parsing, sanitization or bundling. CSP, permissions and visibility are declarations for the host, not access control implemented by the server. The browser renders the interface and the host mediates communication. Local protocol checks do not establish real-host rendering or permission behavior. No runtime, transport or background work is started by this crate.
Structs§
- AppRouter
- An rmcp tool router and exact-URI registry of HTML resources.
- AppServer
- A ready-to-serve MCP server for a prepared application router and its state.
- Meta
Object - An open MCP metadata map, reused from rmcp for extension annotations.
- Permission
Request - An object-valued request for a browser permission, serialized as
{}. - Resource
Ui - Security and rendering declarations for a UI resource.
- ToolUi
- UI association and visibility declarations for a server tool.
- UiCapability
- A validated, borrowed client declaration of MCP Apps support.
- UiCsp
- Origin declarations from which the host constructs a Content Security Policy.
- UiPermissions
- Browser permission requests declared by a UI resource.
- UiResource
- A named UI resource used to prepare a descriptor and matching HTML contents.
- UiResource
Route - A registered HTML source with fixed identity and resource metadata.
- UiResource
Uri - An owned UI resource URI with valid RFC 3986 syntax and a literal
ui://prefix.
Enums§
- Capability
Error - A malformed MCP Apps client capability declaration.
- Metadata
Error - Metadata could not be prepared or composed with existing annotations.
- Registration
Error - A registration or finalization failure, before serving requests.
- UiUri
Error - A failure to construct a
UiResourceUri. - UiVisibility
- An actor allowed to discover or invoke a tool under its UI visibility policy.
Constants§
- UI_
EXTENSION_ ID - The standard MCP Apps capability extension identifier.
- UI_
MIME_ TYPE - The MCP Apps HTML MIME type required on returned resource contents.
Traits§
- Static
UiResource - A UI resource whose HTML is embedded in the consuming binary.
Functions§
- declare_
ui_ extension - Declare MCP Apps support in the server’s extension capabilities.
- ui_
capability - Inspect the client’s MCP Apps extension declaration.
Type Aliases§
- Html
Future - The send-capable result of an HTML resource callback.
Attribute Macros§
- app_
router - Declare an application’s rmcp tools and their static UI resources together.
Derive Macros§
- Static
UiResource - Derive a static resource’s declaration, embedded HTML and optional metadata.