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
Prompts are reusable, parameterized templates that a server exposes to clients so they can generate structured messages for a language model. Register a prompt with server.prompt(), validate its arguments with a Zod schema, and return either a GetPromptResult directly or a response helper result (such as text()) that the server converts for you. To give clients IDE-style autocomplete on prompt arguments, wrap individual schema fields with completable(). 
import { MCPServer, completable } from "mcp-use/server"
import type {
  PromptDefinition,
  PromptCallback,
  PromptResult,
  GetPromptResult,
  Completable,
  CompletionContext,
} from "mcp-use/server"

​
Methods

Registers a prompt template that clients can use to generate formatted messages for a language model. 
import { MCPServer } from "mcp-use/server"

​
prompt

Registers a prompt template on the server and returns the server instance for method chaining. The prompt accepts arguments validated by its Zod schema and returns prompt messages. The callback may be supplied two ways: as a separate callback argument (recommended), or as a cb property on the definition object (legacy). At least one of them must be present, otherwise registration throws. The callback can return a GetPromptResult (an object with a messages array) directly, or any response helper result such as text(), markdown(), or object(). When the returned value has a messages array it is used as-is; any other value is treated as a CallToolResult and converted to a GetPromptResult before being sent. The prompt name is added to the server’s registered prompt list. After registering at runtime, call server.sendPromptsListChanged() so connected clients refresh their list. 
from "mcp-use/server"
Parameters
​
promptDefinition
PromptDefinition | PromptDefinitionWithoutCallback
required
Prompt configuration object. See PromptDefinition for all fields. Use PromptDefinitionWithoutCallback (no cb field) when passing the callback as the second argument.
​
callback
PromptCallback<InferPromptInput<T>, HasOAuth>
Optional callback that receives the validated arguments and returns the prompt result. Required unless the definition includes a cb property. The argument type is inferred from promptDefinition.schema. See PromptCallback.
Returns
​
returns
this
The server instance, for method chaining.
Throws
​
Error
Error
Thrown synchronously during registration when the prompt has neither a cb property nor a callback argument. The message is Prompt '<name>' must have either a cb property or a callback parameter.
Signature 
public prompt: <T extends PromptDefinition<any, HasOAuth> | PromptDefinitionWithoutCallback>(promptDefinition: T & (PromptDefinition<any, HasOAuth> | PromptDefinitionWithoutCallback), callback?: PromptCallback<InferPromptInput<T>, HasOAuth>) => this
Example 
import { MCPServer, text } from "mcp-use/server"
import z from "zod"

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

server.prompt(
  {
    name: "greeting",
    description: "A simple prompt that returns a greeting",
    schema: z.object({
      name: z.string(),
    }),
  },
  async ({ name }) => text(`Hello, ${name}!`)
)

await server.listen()

​
Functions

​
completable()

Attaches autocompletion to a Zod schema so clients can request suggestions. 
import { completable } from "mcp-use/server"
Wraps a Zod schema so MCP clients can request autocomplete suggestions for the field via the protocol’s completion/complete request. Use it on individual fields inside a prompt’s (or resource template’s) schema. It returns the same schema with completion metadata attached, so the field still validates exactly as before. There are two ways to supply suggestions:
  • List-based (primitives only): pass an array of allowed values. The server filters them with a case-insensitive prefix match against what the user has typed. Only z.string(), z.number(), and z.enum([...]) schemas are accepted in this form.
  • Callback-based (any schema): pass a function that receives the current input value and an optional CompletionContext and returns the suggestions (or a promise of them). Use this for dynamic or contextual completion, including suggestions that depend on other already-provided arguments via context.arguments.
from "mcp-use/server"
Parameters
​
schema
T extends z.ZodTypeAny
required
The Zod schema for the argument (for example z.string(), z.number(), z.enum([...])). For the list-based overload, T is constrained to z.ZodString | z.ZodNumber | z.ZodEnum<any>.
​
complete
z.infer<T>[] | ((value, context?) => Promise<...> | ...)
required
Either an array of allowed values (primitives), or a completion callback (value: SchemaInput<T>, context?: CompletionContext) => Promise<SchemaInput<T>[]> | SchemaInput<T>[].
Returns
​
returns
CompletableSchema<T>
The same schema with completion metadata attached. See Completable.
Signature 
// Overload 1: list of allowed values (primitives only)
function completable<T extends z.ZodString | z.ZodNumber | z.ZodEnum<any>>(
  schema: T,
  complete: z.infer<T>[]
): CompletableSchema<T>

// Overload 2: completion callback (any schema)
function completable<T extends z.ZodTypeAny>(
  schema: T,
  complete: (
    value: SchemaInput<T>,
    context?: CompletionContext
  ) => Promise<SchemaInput<T>[]> | SchemaInput<T>[]
): CompletableSchema<T>
Example 
import { MCPServer, completable } from "mcp-use/server"
import { z } from "zod"

const server = new MCPServer({
  name: "completion-example-server",
  version: "1.0.0",
  description:
    "An MCP server example demonstrating completion capabilities for prompt and resource template arguments",
})

// Prompt with static list completion - languages for code review
server.prompt(
  {
    name: "code-review",
    schema: z.object({
      language: completable(z.string(), [
        "python",
        "typescript",
        "javascript",
        "java",
        "go",
        "rust",
      ]),
      severity: z.string(),
    }),
  },
  async ({ language, severity }) => ({
    messages: [
      {
        role: "user",
        content: {
          type: "text",
          text: `Review code in ${language} with ${severity} severity`,
        },
      },
    ],
  })
)

// Prompt with dynamic callback completion - file extensions
server.prompt(
  {
    name: "file-search",
    schema: z.object({
      extension: completable(z.string(), async (value: string) => {
        const extensions = [".ts", ".tsx", ".js", ".jsx", ".py", ".go", ".md"]
        return extensions.filter((ext) => ext.startsWith(value))
      }),
      directory: z.string(),
    }),
  },
  async ({ extension, directory }) => ({
    messages: [
      {
        role: "user",
        content: {
          type: "text",
          text: `Find files with extension ${extension} in ${directory}`,
        },
      },
    ],
  })
)

await server.listen()

​
Types

​
PromptDefinition

Configuration object describing a prompt, including its callback (legacy single-object pattern). 
import type { PromptDefinition } from "mcp-use/server"
Describes a prompt’s metadata, input schema, and callback. This is the variant that carries the callback inline via the cb field. When passing the callback as a separate argument to server.prompt(), use PromptDefinitionWithoutCallback (the same shape minus the cb field). The interface is generic over TInput (the validated argument type) and HasOAuth (whether OAuth is configured, which affects ctx.auth availability). 
from "mcp-use/server"
Properties
​
name
string
required
Unique identifier for the prompt (for example "code-review-template").
​
title
string
Human-readable title displayed in prompt lists.
​
description
string
Description of what the prompt does; helps users choose the right prompt. Defaults to an empty string when omitted.
​
args
InputDefinition[]
Argument definitions. Deprecated, use schema instead.
​
schema
z.ZodObject<any>
Zod object schema for input validation. Call .describe() on each field for user guidance, and wrap fields with completable() to enable autocompletion.
​
cb
PromptCallback<TInput, HasOAuth>
required
Async callback that generates the prompt. Required on this interface; omit it (and pass the callback separately) by using PromptDefinitionWithoutCallback.
Signature 
interface PromptDefinition<TInput = Record<string, any>, HasOAuth extends boolean = false> {
  name: string
  title?: string
  description?: string
  /** @deprecated Use schema instead */
  args?: InputDefinition[]
  schema?: z.ZodObject<any>
  cb: PromptCallback<TInput, HasOAuth>
}

​
PromptCallback

The function signature for a prompt’s handler. 
import type { PromptCallback } from "mcp-use/server"
The handler invoked when a client requests a prompt. It receives the validated arguments as its first parameter and an EnhancedPromptContext as an optional second parameter, and returns a promise. The context exposes auth (when OAuth is configured), req (the Hono request), and client (a capability checker). Parameters are checked bivariantly so you can freely destructure the argument object. The return type is a union: a CallToolResult, a GetPromptResult, or a TypedCallToolResult<any>. In practice this means you can return a response helper such as text() or markdown(), or return a GetPromptResult object literal with a messages array. See PromptResult for the shape server.prompt() ultimately sends. 
from "mcp-use/server"
Type Parameters
​
TInput
Record<string, any>
default:"Record<string, any>"
Type of the validated argument object. Inferred from the definition’s schema.
​
HasOAuth
boolean
default:"false"
Whether OAuth is configured, which controls availability of ctx.auth.
Signature 
type PromptCallback<TInput = Record<string, any>, HasOAuth extends boolean = false> = (
  params: TInput,
  ctx: EnhancedPromptContext<HasOAuth>
) => Promise<CallToolResult | GetPromptResult | TypedCallToolResult<any>>
Example 
import { MCPServer } from "mcp-use/server"
import z from "zod"

const server = new MCPServer({ name: "prompts", version: "1.0.0" })

// Returning a GetPromptResult directly from the callback
server.prompt(
  {
    name: "greeting",
    description: "A simple prompt that returns a greeting",
    schema: z.object({ name: z.string() }),
  },
  async ({ name }) => ({
    messages: [
      {
        role: "user",
        content: { type: "text", text: `Hello, ${name}!` },
      },
    ],
  })
)

​
PromptResult

The value a prompt resolves to. An alias of GetPromptResult. 
import type { PromptResult } from "mcp-use/server"
A naming alias for GetPromptResult, re-exported from the MCP SDK for convenience. Use it wherever you want to refer to the result a prompt produces. It is the exact same type as GetPromptResult; the two are interchangeable. 
from "mcp-use/server"
Signature 
type PromptResult = GetPromptResult

​
GetPromptResult

The structured result returned to a client for a prompts/get request. 
import type { GetPromptResult } from "mcp-use/server"
The MCP protocol result for retrieving a prompt, re-exported from @modelcontextprotocol/sdk. It carries an array of messages plus an optional description and _meta. Each message has a role of "user" or "assistant" and a content object whose type is one of "text", "image", "audio", or an embedded resource. When server.prompt() detects a returned value with a messages array it forwards it unchanged; otherwise it converts the value (a CallToolResult from a response helper) into this shape. 
from "mcp-use/server"
Properties
​
messages
PromptMessage[]
required
Ordered list of messages that make up the prompt. Each is { role: "user" | "assistant"; content: ... }.
​
description
string
Optional human-readable description of the prompt result.
​
_meta
object
Optional protocol metadata.
Signature 
type GetPromptResult = {
  messages: Array<{
    role: "user" | "assistant"
    content:
      | { type: "text"; text: string }
      | { type: "image"; data: string; mimeType: string }
      | { type: "audio"; data: string; mimeType: string }
      | { type: "resource"; resource: unknown }
  }>
  description?: string
  _meta?: { [key: string]: unknown }
}

​
Completable

A type alias for a schema that has completion metadata attached. 
import type { Completable } from "mcp-use/server"
A utility type alias for the result of completable(). Use it when you need to annotate or reference a completable schema’s type. It is generic over the wrapped Zod schema type T. 
from "mcp-use/server"
Type Parameters
​
T
z.ZodTypeAny
required
The wrapped Zod schema type.
Signature 
type Completable<T extends z.ZodTypeAny> = CompletableSchema<T>
Example 
import type { Completable } from "mcp-use/server"
import type { z } from "zod"

type LanguageSchema = Completable<z.ZodString>

​
CompletionContext

Context passed to a completion callback, exposing the other argument values. 
import type { CompletionContext } from "mcp-use/server"
Passed as the optional second argument to a callback-based completable(). It carries the other argument values already supplied for the same prompt or resource template, which lets you produce contextual suggestions (for example, narrowing project suggestions by an earlier userId). The arguments property is optional, so guard for undefined before reading from it. 
from "mcp-use/server"
Properties
​
arguments
Record<string, unknown>
Other argument values from the same prompt or resource template. Useful for contextual completion based on previously provided values.
Signature 
interface CompletionContext {
  arguments?: Record<string, unknown>
}
Example 
import { MCPServer, completable } from "mcp-use/server"
import { z } from "zod"
import type { CompletionContext } from "mcp-use/server"

const server = new MCPServer({ name: "prompts", version: "1.0.0" })

server.prompt(
  {
    name: "analyze-project",
    schema: z.object({
      projectId: completable(
        z.string(),
        async (value: string, ctx?: CompletionContext) => {
          const userId = ctx?.arguments?.userId
          const projects = await fetchProjects(userId)
          return projects
            .map((p) => p.id)
            .filter((id) => id.startsWith(value))
        }
      ),
    }),
  },
  async ({ projectId }) => ({
    messages: [
      {
        role: "user",
        content: { type: "text", text: `Analyzing ${projectId}...` },
      },
    ],
  })
)