Prompts

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

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

The prompt file should export three elements:

• Schema: The input parameters using Zod schemas.
• Metadata: The prompt's identity and behavior hints.
• Default: The prompt handler function.

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

// Define the schema for prompt parameters
export const schema = {
  code: z.string().describe("The code to review"),
};

// Define prompt metadata
export const metadata: PromptMetadata = {
  name: "review-code",
  title: "Review Code",
  description: "Review code for best practices and potential issues",
  role: "user",
};

// Prompt implementation
export default function reviewCode({ code }: InferSchema<typeof schema>) {
  return {
    type: "text",
    text: `Please review this code for:
      - Code quality and best practices
      - Potential bugs or security issues
      - Performance optimizations
      - Readability and maintainability

      Code to review:
      \`\`\`
      ${code}
      \`\`\``,
  };
}

If you're returning a string or number only, you can shortcut the return value to be the string or number directly.

export default function reviewCode({ code }: InferSchema<typeof schema>) {
  return `Please review this code for:
    - Code quality and best practices
    - Potential bugs or security issues
    - Performance optimizations
    - Readability and maintainability

    Code to review:
    \`\`\`
    ${code}
    \`\`\``;
  `;
}

Multi-message prompts

Return a PromptMessage[] to provide a conversation, such as examples followed by a new question. Each message must have a user or assistant role and a content object. xmcp validates every message and preserves their order and roles. metadata.role only applies when returning a single content object, string, or number; its default remains assistant.

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

export const schema = {
  text: z.string().describe("The text to classify"),
};

export default function classifySentiment({
  text,
}: InferSchema<typeof schema>): PromptMessage[] {
  return [
    { role: "user", content: { type: "text", text: "Classify: I love it" } },
    { role: "assistant", content: { type: "text", text: "positive" } },
    { role: "user", content: { type: "text", text: "Classify: I dislike it" } },
    { role: "assistant", content: { type: "text", text: "negative" } },
    { role: "user", content: { type: "text", text: `Classify: ${text}` } },
  ];
}

Return a full GetPromptResult when you also need a description or result metadata. Both types are available from xmcp, and async handlers can return either shape.

import type { GetPromptResult } from "xmcp";

export default function welcome(): GetPromptResult {
  return {
    description: "Start a conversation",
    messages: [
      { role: "user", content: { type: "text", text: "Introduce yourself" } },
      {
        role: "assistant",
        content: { type: "text", text: "Hello! How can I help?" },
      },
    ],
    _meta: { source: "welcome-template" },
  };
}

Messages can contain text, images, audio, resource links, or embedded resources. An invalid result throws an error identifying the field, such as messages.1.role. Empty message arrays are allowed. Full results retain their description and metadata.

The HTTP transport example includes a runnable classify-sentiment prompt and a request to try it.

References

Schema (optional)

The schema object defines the prompt's parameters with:

• Key: Parameter name.
• Value: Zod schema with .describe() for documentation and prompt 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.

Metadata (optional)

The metadata object provides:

• Name: Unique identifier for the prompt
• Title: Human-readable title for the prompt
• Description: Brief explanation of what the prompt does
• Role: The role for single content, string, or number returns. Can be either user or assistant; defaults to assistant. Message arrays and full results use each message's explicit role.

Icons, tags, and availability

PromptMetadata accepts optional icons, tags, and enabled fields:

import type { PromptMetadata } from "xmcp";

export const metadata: PromptMetadata = {
  name: "review-code",
  title: "Review Code",
  description: "An example prompt",
  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.

Prompts are enabled by default. Set enabled: false to skip registration: the prompt is absent from prompts/list, and prompts/get returns a not-found error. Custom metadata._meta values are also exposed in prompts/list.

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: A string, number, content object, PromptMessage[], or full GetPromptResult.
• Async: Supports async operations for API calls, file I/O, etc.

Troubleshooting

Prompt Loading Errors

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

• Empty prompt 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/prompts/draft.ts is empty, startup will log:

[xmcp] Failed to load prompt file: src/prompts/draft.ts
   -> File is empty.
[xmcp] 1 prompt 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 prompt file: src/prompts/draft.ts
   -> File does not export a default prompt handler.