Resources

For the complete documentation index, see llms.txt. Markdown variants of every page are available by appending .md to the URL.

xmcp automatically detects and registers files under the /src/resources/ directory as resources. This path can be configured in your xmcp.config.ts file.

Resource files can export:

• Schema: Input parameters defined using Zod schemas
• Metadata: The resource's identity and behavior configuration
• Default: The resource handler function
• Complete (optional): Suggestions for dynamic URI parameters

There are two types of resources: static and dynamic. When creating resources, it's important to understand how the folder structure determines the resource URI.

URI composition rules

Each resource is uniquely identified by a URI composed from its file path using these rules:

• The URI scheme is detected from folders with parentheses. For example, a parent folder named (users) creates the URI scheme users.
• Static folders become literal path segments.
• Brackets [] indicate dynamic parameters.

For example, the following file path:

src/resources/(users)/[userId]/profile.ts

Will result in the URI users://{userId}/profile.

1. Static resource

Static resources are files that don't require any parameters. Following the composition rules above, the resource below will have the URI config://app:

import { type ResourceMetadata } from "xmcp";

export const metadata: ResourceMetadata = {
  name: "app-config",
  title: "Application Config",
  description: "Application configuration data",
};

export default function handler() {
  return "App configuration here";
}

2. Dynamic resource

Dynamic resources accept parameters. The example below creates a resource with the URI users://{userId}/profile:

import { z } from "zod";
import { type ResourceMetadata, type InferSchema } from "xmcp";

export const schema = {
  userId: z.string().describe("The ID of the user"),
};

export const metadata: ResourceMetadata = {
  name: "user-profile",
  title: "User Profile",
  description: "User profile information",
};

export default function handler({ userId }: InferSchema<typeof schema>) {
  return `Profile data for user ${userId}`;
}

Resource-template completion

Export a complete object from a dynamic resource file to suggest values for its URI parameters. Each key matches a bracketed parameter in the file path. Callbacks receive the current input string and optional context containing other arguments the client has already entered. Return a string array, or a promise of one; the callback decides how to filter suggestions.

import type { ResourceCompletions } from "xmcp";

export const complete: ResourceCompletions = {
  team: (value) =>
    ["engineering", "sales"].filter((team) => team.startsWith(value)),
  member: async (value, context) => {
    const names =
      context?.arguments?.team === "engineering" ? ["ada", "alan"] : ["sam"];
    return names.filter((name) => name.startsWith(value));
  },
};

export default function member({
  team,
  member,
}: {
  team: string;
  member: string;
}) {
  return `Profile for ${member} on ${team}`;
}

Clients request completion/complete with the exact URI template returned by resources/templates/list, retaining {parameter} placeholders:

{
  "ref": { "type": "ref/resource", "uri": "teams://{team}/{member}" },
  "argument": { "name": "member", "value": "a" },
  "context": { "arguments": { "team": "engineering" } }
}

This returns suggestions ada and alan. Context is supplied by the current request; it is not stored between calls. Unknown parameters and parameters without a callback return an empty list when completion is enabled. Callback keys outside the URI template are ignored, as is complete on static resources. Servers with no completion callbacks keep completion disabled.

Responses contain at most 100 suggestions, preserving callback order. The SDK reports total and hasMore if the callback returns more. Completion does not restrict subsequent resource reads; keep validation in your schema or handler. Prompt argument completion through completable() continues to work alongside resource completion.

The HTTP transport example includes user ID completion and a runnable request.

Requesting client input

Static resources and resource templates can return inputRequired(...) when they need client input before producing their contents, such as the client's workspace roots via inputRequired.listRoots().

Read the response with inputResponse(extra.mcpReq.inputResponses, requestId) from the handler's second argument. If the response is missing, return the input request; on retry, use the supplied response to return the resource contents. The SDK handles negotiation and retries. Keep request data in the current request rather than saving it on the server.

See multi round-trip input for the input request helpers.

References

Schema (optional)

The schema object defines the resource's parameters with:

• Key: Parameter name.
• Value: Zod schema with .describe() for documentation and resource inspection. This will be visible through the inspector.
• Purpose: Type validation and automatic parameter documentation.

This is the exact same as the schema object for tools and prompts.

Metadata (optional)

The metadata object provides:

• Name: Unique identifier for the resource
• Title: Human-readable title for the resource
• Description: Brief explanation of what the resource does
• MimeType: The MIME type of the resource
• Size: The size of the resource

Icons, tags, and availability

ResourceMetadata accepts optional icons, tags, and enabled fields:

import type { ResourceMetadata } from "xmcp";

export const metadata: ResourceMetadata = {
  name: "app-config",
  description: "An example resource",
  icons: [
    {
      src: "https://example.com/icon.png",
      mimeType: "image/png",
      sizes: ["48x48"],
      theme: "dark",
    },
  ],
  tags: ["example"],
  enabled: true,
};

Icons are forwarded to MCP clients. Each icon requires src (a URL or data URI) and may include mimeType, sizes, and theme ("light" or "dark"). Tags appear in listings under _meta["xmcp/tags"]; other metadata is preserved. When both tags and _meta["xmcp/tags"] are supplied, tags takes precedence. Tags alone do not change availability. Use component visibility rules to include or exclude components by name or tag in xmcp.config.ts.

Static resources and resource templates are enabled by default. Set enabled: false to skip registration: the resource is absent from resources/list or resources/templates/list, and resources/read returns a not-found error for its URI. These options are identical for both resource types.

Availability is evaluated during server setup; modules are still imported. Rebuild and restart the server after changing metadata in production.

The HTTP transport example demonstrates icons, tags, and a disabled experimental tool.

Implementation (required)

The default export function that performs the actual work.

• Parameters: Automatically typed from your schema using the built-in InferSchema.
• Returns: MCP-compatible response with content type.

Troubleshooting

Resource Loading Errors

When xmcp starts, it loads every file under your resources directory.

• Empty resource files are skipped with a friendly warning
• Files without a default export are skipped with a friendly warning
• Real syntax or import errors still fail normally so you can see the full stack trace

For example, if src/resources/(drafts)/latest.ts is empty, startup will log:

[xmcp] Failed to load resource file: src/resources/(drafts)/latest.ts
   -> File is empty.
[xmcp] 1 resource skipped due to empty files or missing default exports

If the file exists but does not export a default handler, startup will log:

[xmcp] Failed to load resource file: src/resources/(drafts)/latest.ts
   -> File does not export a default resource handler.