> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcp-use.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Prompts

> Register prompt templates and add argument autocompletion API Documentation

**Source Code**

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](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/src/server/mcp-server.ts)](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()`.

```ts theme={null}
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.

```ts theme={null}
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.

```ts theme={null}
from "mcp-use/server"
```

**Parameters**

> **promptDefinition** `PromptDefinition | PromptDefinitionWithoutCallback` *required*
>
> Prompt configuration object. See [PromptDefinition](#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](#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**

```ts wrap theme={null}
public prompt: <T extends PromptDefinition<any, HasOAuth> | PromptDefinitionWithoutCallback>(promptDefinition: T & (PromptDefinition<any, HasOAuth> | PromptDefinitionWithoutCallback), callback?: PromptCallback<InferPromptInput<T>, HasOAuth>) => this
```

**Example**

```ts wrap theme={null}
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.

```ts theme={null}
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`](#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`.

```ts theme={null}
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`](#completable-1).

**Signature**

```ts wrap theme={null}
// 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**

```ts wrap theme={null}
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).

```ts theme={null}
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).

```ts theme={null}
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()`](#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**

```ts wrap theme={null}
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.

```ts theme={null}
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`](https://docs.mcp-use.com/v1/typescript/api-reference/server/tool-context) 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](#promptresult) for the shape `server.prompt()` ultimately sends.

```ts theme={null}
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**

```ts wrap theme={null}
type PromptCallback<TInput = Record<string, any>, HasOAuth extends boolean = false> = (
  params: TInput,
  ctx: EnhancedPromptContext<HasOAuth>
) => Promise<CallToolResult | GetPromptResult | TypedCallToolResult<any>>
```

**Example**

```ts wrap theme={null}
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`.

```ts theme={null}
import type { PromptResult } from "mcp-use/server"
```

A naming alias for [`GetPromptResult`](#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.

```ts theme={null}
from "mcp-use/server"
```

**Signature**

```ts wrap theme={null}
type PromptResult = GetPromptResult
```

### GetPromptResult

The structured result returned to a client for a `prompts/get` request.

```ts theme={null}
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.

```ts theme={null}
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**

```ts wrap theme={null}
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.

```ts theme={null}
import type { Completable } from "mcp-use/server"
```

A utility type alias for the result of [`completable()`](#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`.

```ts theme={null}
from "mcp-use/server"
```

**Type Parameters**

> **T** `z.ZodTypeAny` *required*
>
> The wrapped Zod schema type.

**Signature**

```ts wrap theme={null}
type Completable<T extends z.ZodTypeAny> = CompletableSchema<T>
```

**Example**

```ts wrap theme={null}
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.

```ts theme={null}
import type { CompletionContext } from "mcp-use/server"
```

Passed as the optional second argument to a callback-based [`completable()`](#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.

```ts theme={null}
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**

```ts wrap theme={null}
interface CompletionContext {
  arguments?: Record<string, unknown>
}
```

**Example**

```ts wrap theme={null}
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}...` },
      },
    ],
  })
)
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.