Define MCP Prompts

Apollo MCP Server supports MCP 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
prompts/check_orders.md
1---
2name: check_orders
3description: "Look up a user's recent orders and summarize them"
4arguments:
5  - name: email
6    description: "The customer's email address"
7    required: true
8  - name: limit
9    description: "Maximum number of orders to return"
10---
11
121. Use GetUserByEmail(email={{email}}) to find the user
132. Use GetUserOrders to retrieve their recent orders{{limit}}
143. Summarize each order with its status, total, and date

Frontmatter fields

FieldTypeRequiredDescription
namestringYesUnique identifier for the prompt, used in prompts/get requests
descriptionstringNoHuman-readable description shown to AI clients
argumentslistNoArguments the prompt accepts

The arguments list supports the following fields:

FieldTypeDefaultDescription
namestring—Argument name, used as the {{name}} placeholder in the template
descriptionstring—Description shown to AI clients
requiredbooleanfalseWhether 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
prompts/astronaut_bio.md
1---
2name: astronaut_bio
3description: "Look up an astronaut and write a short biography"
4arguments:
5  - name: name
6    description: "The astronaut's name to search for"
7    required: true
8---
9
101. Search for an astronaut named "{{name}}"
112. Use GetAstronautDetails to get their full profile
123. Write a concise biography covering their background and missions

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

JSON
1{"name": "astronaut_bio", "arguments": {"name": "Chris Hadfield"}}

...the client receives a single user message:

Text
11. Search for an astronaut named "Chris Hadfield"
22. Use GetAstronautDetails to get their full profile
33. 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
Feedback

Edit on GitHub

Ask Community