> ## 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

> Create reusable MCP prompt templates with typed arguments.

Prompts package repeatable model instructions. Use a prompt when a client should
request model-ready messages; use a tool when the server should perform work.

## Register a prompt

Prompt schemas are Standard Schema-compatible. Zod is one option:

```typescript theme={null}
import { MCPServer } from "mcp-use";
import { z } from "zod";

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

server.prompt(
  {
    name: "review-code",
    description: "Create a focused code-review request.",
    schema: z.object({
      language: z.string(),
      code: z.string(),
    }),
  },
  async ({ language, code }) => ({
    messages: [
      {
        role: "user",
        content: {
          type: "text",
          text: `Review this ${language} code for correctness and security:\n\n${code}`,
        },
      },
    ],
  }),
);

export default server;
```

Prefer the raw `{ messages: [...] }` result. Each message has a role and one
MCP content block.

## Add argument suggestions

`completable()` supplies suggestions to clients. It does not constrain valid
values; the wrapped schema still decides what input is valid.

Apply descriptions, defaults, and refinements before wrapping the field:

```typescript theme={null}
import { completable } from "mcp-use";

server.prompt(
  {
    name: "summarize-project",
    schema: z.object({
      team: completable(z.string().min(1).describe("Owning team"), [
        "platform",
        "sales",
        "support",
      ]),
      projectId: completable(
        z.string().min(1).describe("Project identifier"),
        async (value, context) => {
          const team = context?.arguments?.team as string | undefined;
          return (await projects.search({ team, query: value })).map(
            (project) => project.id,
          );
        },
      ),
    }),
  },
  async ({ team, projectId }) => ({
    messages: [
      {
        role: "user",
        content: {
          type: "text",
          text: `Summarize project ${projectId} for the ${team} team.`,
        },
      },
    ],
  }),
);
```

Use an enum when only a fixed set is valid. Use `completable(z.string(), ...)`
when other strings remain acceptable.

## Use verified authentication context

Configure OAuth before reading `ctx.auth`. The authenticated callback type then
contains the provider's mapped user:

```typescript theme={null}
import { MCPServer } from "mcp-use";
import { oauthAuth0Provider } from "mcp-use/oauth/auth0";

const authenticatedServer = new MCPServer({
  name: "personal-prompts",
  version: "1.0.0",
  oauth: oauthAuth0Provider({
    domain: process.env.AUTH0_DOMAIN!,
  }),
});

authenticatedServer.prompt({ name: "weekly-summary" }, async (_args, ctx) => ({
  messages: [
    {
      role: "user",
      content: {
        type: "text",
        text: `Create a weekly summary for user ${ctx.auth.user.id}.`,
      },
    },
  ],
}));
```

Use app-owned configuration validation in production rather than a non-null
assertion. Client-reported metadata is not an authentication substitute.

## Notify prompt-list listeners

Register prompts while constructing the server, before it starts handling
requests. When application state changes what clients should consider
available, publish a prompt-list invalidation:

```typescript theme={null}
await server.notifyPromptsChanged();
```

Active subscription listeners can then request `prompts/list` again. The
server registry itself is not designed for late prompt registration after
startup.

## Test prompts

Run `mcp-use dev`, open the built-in inspector, and verify listing, argument
validation, completions, and the exact generated messages.