---
title: Define MCP Prompts
---

Apollo MCP Server supports [MCP prompts](https://modelcontextprotocol.io/docs/concepts/prompts)—reusable prompt templates that AI clients can discover and use. These prompts operate as guided workflows that help AI models use your GraphQL tools more effectively.

## How prompts work

Each prompt is a Markdown file with YAML frontmatter that defines its name, description, and arguments. The file body is the prompt template, which includes `{{argument}}` placeholders that the AI client substitutes with values at runtime.

When the server starts, it loads all `.md` files from a `prompts/` directory, which is in the working directory. If that directory contains valid prompt files, the server advertises prompt support to MCP clients with the `prompts` feature.

## Define your prompts

Store your prompt files in a `prompts/` directory in your server's working directory. Each `.md` file in this directory becomes an MCP prompt.

### Prompt file format

A prompt file has two parts separated by `---` delimiters:

1. YAML frontmatter with the prompt metadata
2. Template body with the prompt content

```markdown title="prompts/check_orders.md"
---
name: check_orders
description: "Look up a user's recent orders and summarize them"
arguments:
  - name: email
    description: "The customer's email address"
    required: true
  - name: limit
    description: "Maximum number of orders to return"
---

1. Use GetUserByEmail(email={{email}}) to find the user
2. Use GetUserOrders to retrieve their recent orders{{limit}}
3. Summarize each order with its status, total, and date
```

### Frontmatter fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | `string` | Yes | Unique identifier for the prompt, used in `prompts/get` requests |
| `description` | `string` | No | Human-readable description shown to AI clients |
| `arguments` | list | No | Arguments the prompt accepts |

The `arguments` list supports the following fields:

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `name` | `string` | — | Argument name, used as the `{{name}}` placeholder in the template |
| `description` | `string` | — | Description shown to AI clients |
| `required` | boolean | `false` | Whether the argument must be provided |

### Template placeholders

Use `{{argument_name}}` in the template body to reference arguments. When an AI client calls `prompts/get` with argument values, the server replaces each placeholder with the corresponding value.

Placeholders that don't match any provided argument are left unchanged in the output.

## Example

If this prompt file is provided...

```markdown title="prompts/astronaut_bio.md"
---
name: astronaut_bio
description: "Look up an astronaut and write a short biography"
arguments:
  - name: name
    description: "The astronaut's name to search for"
    required: true
---

1. Search for an astronaut named "{{name}}"
2. Use GetAstronautDetails to get their full profile
3. Write a concise biography covering their background and missions
```

An AI client calling `prompts/get` with the following request:

```json
{"name": "astronaut_bio", "arguments": {"name": "Chris Hadfield"}}
```

...the client receives a single user message:

```text
1. Search for an astronaut named "Chris Hadfield"
2. Use GetAstronautDetails to get their full profile
3. Write a concise biography covering their background and missions
```

## Behavior

- **No configuration required.** The server automatically detects the `prompts/` directory.
- **Graceful degradation.** If the `prompts/` directory doesn't exist, the server starts normally without advertising prompt support.
- **Validation.** Apollo MCP Server validates that required arguments are present when a prompt is requested. Missing required arguments return an error.
- **Single message.** Each prompt returns a single user-role text message. Multi-message and non-text content types aren't currently supported.

## See also

- [Define MCP Tools](/apollo-mcp-server/define-tools) — Expose GraphQL operations as MCP tools
- [YAML Config Reference](/apollo-mcp-server/config-file) — Full configuration options for Apollo MCP Server
