Skip to main content
View the source code for this module on GitHub: https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/src/server/mcp-server.ts
Resources expose data and content that MCP clients can read by URI: configuration, files, database records, API responses, and more. Register a single fixed resource with server.resource(), or register a parameterized family of resources with server.resourceTemplate(). Both methods are members of the MCPServer class and return this, so calls can be chained.

​
Resource Registration

Registration methods for static and templated resources, plus the related definition and callback types. 
import { MCPServer } from "mcp-use/server";

​
Methods

​
server.resource()

Registers a static resource that clients can read at a fixed URI. A resource represents a single addressable piece of content (configuration, a status snapshot, a document) identified by its uri. The content is produced by a ReadResourceCallback, which may be passed as the second argument or supplied as the readCallback field on the definition. If neither a callback argument nor a readCallback field is present, registration throws an Error. Resources are keyed internally by `${name}:${uri}`, so a unique name plus uri pair avoids collisions. Use server.resourceTemplate() instead when the URI contains parameters. Parameters
​
resourceDefinition
ResourceDefinition<HasOAuth> | ResourceDefinitionWithoutCallback
required
Resource configuration object. Use ResourceDefinition (with a readCallback and a required mimeType) or ResourceDefinitionWithoutCallback (pass the callback as the second argument; mimeType is optional and inferred from response helpers).
​
callback
ReadResourceCallback<HasOAuth>
Async function that returns the resource content. Optional when readCallback is set on the definition.
Returns
​
returns
this
The same MCPServer instance, for method chaining.
Signature 
public resource: (resourceDefinition: ResourceDefinition<HasOAuth> | ResourceDefinitionWithoutCallback, callback?: ReadResourceCallback<HasOAuth>) => this;
Example 
import { MCPServer, markdown } from "mcp-use/server";

const server = new MCPServer({
  name: "simple-example-server",
  version: "1.0.0",
  description: "A simple MCP server example",
});

server.resource(
  {
    name: "greeting",
    uri: "app://greeting",
    title: "Greeting Message",
  },
  async () => markdown("# Hello from mcp-use!")
);

await server.listen();

​
server.resourceTemplate()

Registers a resource template: a family of resources whose URIs share a pattern with {param} placeholders (for example user://{userId}/profile). When a client reads a URI that matches the template, the placeholders are parsed out and passed to the callback. Use this for parameterized reads such as files by path or records by id. The definition may use the nested shape (ResourceTemplateDefinition / ResourceTemplateDefinitionWithoutCallback, where the URI lives under resourceTemplate.uriTemplate) or the flat shape (FlatResourceTemplateDefinition / FlatResourceTemplateDefinitionWithoutCallback, where uriTemplate sits directly on the object). Supplying an optional Zod schema narrows the params argument of the callback to z.infer<schema>. The read handler is taken from the callback argument or, if omitted, from the readCallback field on the definition; if neither is present, registration throws an Error. Templates are keyed internally by name. Parameters
​
templateDefinition
T
required
Resource template configuration. T is one of ResourceTemplateDefinition, ResourceTemplateDefinitionWithoutCallback, FlatResourceTemplateDefinition, or FlatResourceTemplateDefinitionWithoutCallback.
​
callback
ReadResourceTemplateCallback<InferTemplateParams<T>, HasOAuth>
Async function receiving the matched URI and extracted parameters. Optional when readCallback is set on the definition.
Returns
​
returns
this
The same MCPServer instance, for method chaining.
Signature 
public resourceTemplate: <T extends ResourceTemplateDefinition<HasOAuth, any> | ResourceTemplateDefinitionWithoutCallback | FlatResourceTemplateDefinition<HasOAuth, any> | FlatResourceTemplateDefinitionWithoutCallback>(templateDefinition: T, callback?: ReadResourceTemplateCallback<InferTemplateParams<T>, HasOAuth>) => this;
Example 
import { MCPServer, text } from "mcp-use/server";
import { promises as fs } from "node:fs";

const server = new MCPServer({ name: "files-server", version: "1.0.0" });

server.resourceTemplate(
  {
    name: "files",
    uriTemplate: "file:///{path}",
    description: "Read files by path",
  },
  async (uri, params) => {
    const content = await fs.readFile(params.path, "utf-8");
    return text(content);
  }
);

​
Types

​
ResourceDefinition

Configuration object for a static resource registered through server.resource(). This is the inline-callback shape: it carries a required mimeType and a readCallback. To pass the callback as the second argument to server.resource() instead, use ResourceDefinitionWithoutCallback, whose mimeType is optional and inferred from response helpers such as text() or object(). The generic parameter HasOAuth is false by default and controls whether ctx.auth is available inside the callback. Fields
​
name
string
required
Unique identifier for the resource. Example: "app-settings".
​
uri
string
required
URI pattern for accessing the resource. Use a custom scheme such as config:// or app://. Example: "config://app-settings".
​
title
string
Human-readable title. Example: "App Settings".
​
description
string
Description of what the resource contains.
​
mimeType
string
required
MIME type of the resource content (required for this shape).
​
annotations
ResourceAnnotations
Optional annotations for discovery and presentation.
​
readCallback
ReadResourceCallback<HasOAuth>
required
Async callback that returns the resource content.
​
_meta
Record<string, unknown>
Arbitrary metadata attached to the resource.
​
callbacks
ResourceTemplateCallbacks
Optional completion callbacks.
Signature 
interface ResourceDefinition<HasOAuth extends boolean = false> {
  name: string;
  uri: string;
  title?: string;
  description?: string;
  mimeType: string;
  annotations?: ResourceAnnotations;
  readCallback: ReadResourceCallback<HasOAuth>;
  _meta?: Record<string, unknown>;
  callbacks?: ResourceTemplateCallbacks;
}

​
UIResourceDefinition

Discriminated union describing an interactive UI resource (a widget) for clients that support rich rendering, such as ChatGPT (Apps SDK) and MCP Apps clients. Pass a value of this type to server.uiResource(). The active member is chosen by the type discriminant: "externalUrl", "rawHtml", "remoteDom", "appsSdk", or "mcpApps". All members extend a common base providing name, title, description, props, size, annotations, encoding (defaults to "text"), exposeAsTool (defaults to true), toolAnnotations, toolOutput, and _meta. Each member adds its own content fields: externalUrl carries a widget id, rawHtml carries htmlContent, remoteDom carries a script (and optional framework, default "react"), appsSdk carries an htmlTemplate, and mcpApps carries an htmlTemplate plus unified metadata that adapters translate per protocol. Members
​
ExternalUrlUIResource
{ type: 'externalUrl'; widget: string; adapters?; appsSdkMetadata? }
Serves a widget through an iframe (legacy MCP-UI).
​
RawHtmlUIResource
{ type: 'rawHtml'; htmlContent: string; adapters?; appsSdkMetadata? }
Renders direct HTML content (legacy MCP-UI).
​
RemoteDomUIResource
{ type: 'remoteDom'; script: string; framework?; adapters?; appsSdkMetadata? }
Scripted remote-DOM UI components (legacy MCP-UI).
​
AppsSdkUIResource
{ type: 'appsSdk'; htmlTemplate: string; appsSdkMetadata? }
OpenAI Apps SDK compatible widget using the text/html+skybridge mime type.
​
McpAppsUIResource
{ type: 'mcpApps'; htmlTemplate: string; metadata?; appsSdkMetadata? }
Official MCP Apps Extension (SEP-1865) widget with dual-protocol support.
Signature 
type UIResourceDefinition =
  | ExternalUrlUIResource
  | RawHtmlUIResource
  | RemoteDomUIResource
  | AppsSdkUIResource
  | McpAppsUIResource;
Example 
import { MCPServer } from "mcp-use/server";

const server = new MCPServer({
  name: "mcp-apps-gallery",
  version: "1.0.0",
  description: "MCP Apps widget gallery",
});

server.uiResource({
  type: "mcpApps",
  name: "welcome-card",
  title: "Welcome",
  description: "A welcome card with server information",
  htmlTemplate: `<div class="card"><h1>Welcome to MCP Apps</h1></div>`,
  metadata: {
    prefersBorder: true,
    widgetDescription: "Server welcome card",
  },
  exposeAsTool: true,
});

​
ReadResourceCallback

The async handler that produces the content for a static resource. It receives a single ctx argument (an EnhancedResourceContext) carrying request context and a client capability checker, and returns a promise resolving to a CallToolResult (the shape returned by response helpers like text() and object()) or a ReadResourceResult (the older API shape). The generic HasOAuth controls whether ctx.auth is available. Parameters
​
ctx
EnhancedResourceContext<HasOAuth>
required
Request context with req, client (capability checker), and, when OAuth is configured, auth.
Returns
​
returns
Promise<CallToolResult | ReadResourceResult | TypedCallToolResult<any>>
The resource content.
Signature 
type ReadResourceCallback<HasOAuth extends boolean = false> = (
  ctx: EnhancedResourceContext<HasOAuth>
) => Promise<CallToolResult | ReadResourceResult | TypedCallToolResult<any>>;

​
ReadResourceTemplateCallback

The async handler that produces content for a resource template. It is an overloaded union of four signatures so handlers can take only the arguments they need: no arguments, the matched uri only, uri plus extracted params, or uri, params, and ctx. The implementation inspects callback.length (the function arity) to decide which signature applies, so declare exactly the parameters you use. The generic TParams (default Record<string, any>) types the extracted URI parameters and is narrowed automatically when the template definition supplies a Zod schema; HasOAuth controls ctx.auth availability. Parameters
​
uri
URL
The matched resource URI (omit in the zero-argument form).
​
params
TParams
Parameters parsed from the URI template placeholders.
​
ctx
EnhancedResourceContext<HasOAuth>
Request context with req, client, and optional auth.
Returns
​
returns
Promise<CallToolResult | ReadResourceResult | TypedCallToolResult<any>>
The resource content.
Signature 
type ReadResourceTemplateCallback<
  TParams extends Record<string, any> = Record<string, any>,
  HasOAuth extends boolean = false,
> =
  | (() => Promise<CallToolResult | ReadResourceResult | TypedCallToolResult<any>>)
  | ((uri: URL) => Promise<CallToolResult | ReadResourceResult | TypedCallToolResult<any>>)
  | ((uri: URL, params: TParams) => Promise<CallToolResult | ReadResourceResult | TypedCallToolResult<any>>)
  | ((uri: URL, params: TParams, ctx: EnhancedResourceContext<HasOAuth>) => Promise<CallToolResult | ReadResourceResult | TypedCallToolResult<any>>);