# MCP Guide Writer

> Create usage guides for MCP servers in the ToolHive documentation (docs/toolhive/guides-mcp/). Use when asked to write, create, or update a usage guide for an MCP server, e.g. "write a usage guide for the filesystem MCP server" or "document the sqlite MCP server from the registry".

- Skill: `stacklok/mcp-guide-writer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add stacklok/mcp-guide-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/stacklok/mcp-guide-writer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: stacklok (https://skillmd.com/u/stacklok)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/stacklok/mcp-guide-writer

---


# MCP server usage guide writer

Create accurate, user-friendly usage guides that help developers run an MCP server with ToolHive.

**Guide scope**: the guide's job is to get the server working with ToolHive: install, configure, connect a client, and try it out. It is not a tutorial for the upstream server itself. Keep upstream-server caveats and behavior details to a sentence with a link to the server's own documentation.

## Research and information gathering

- Use the `thv registry info <server-name> --format json` command to gather detailed information about the MCP server, including configuration options, capabilities, and requirements.
- Use the `WebFetch` tool, the `fetch` MCP server, or `github` MCP server to retrieve additional documentation from the server's repository.

## Structure

Write guides as MDX files in `docs/toolhive/guides-mcp/` following the `_template.mdx` structure exactly. Each guide must include ONLY these sections:

- Front matter with title, description, last_update author and today's date (`YYYY-MM-DD` format)
- Overview section explaining what the MCP server does
- Metadata section with `<MCPMetadata name='server-name' />` component
- Usage section with tabbed UI/CLI/Kubernetes instructions
- Sample prompts section with practical examples
- Recommended practices section with security and best practices

DO NOT include:

- Available tools/capabilities section (handled by MCPMetadata component)
- Configuration options section (handled by MCPMetadata component)

## Technical accuracy

All configuration examples must be valid and tested. Reference the existing ToolHive documentation in the `docs/toolhive/` directory as the source of truth for:

- Available `thv` CLI commands and their syntax (reference: `docs/toolhive/reference/cli/*.md` or run `thv --help`)
- Kubernetes CRD specifications and fields (reference: `static/api-specs/toolhive-crds/*.schema.json`)
- UI configuration options and workflows (reference: `docs/toolhive/guides-ui/*`)

## Documentation standards

Before drafting, read the tech-writer skill's how-to reference and anti-patterns list (`.claude/skills/tech-writer/references/how-to-guides.md` and `.claude/skills/tech-writer/references/anti-patterns.md`); usage guides are how-to guides and follow that mode's discipline.

Adhere to the project's writing style guide (`STYLE-GUIDE.md`) including:

- Use US English with casual, conversational tone
- Address readers in second person ("you", "your")
- Use sentence case for headings
- Apply proper Markdown formatting (ATX headings, fenced code blocks with language tags)
- Include descriptive alt text for images
- Use admonitions (`:::note`, `:::tip`, `:::warning`) for important information, using `:::tip[Title]` format for custom titles

## Practical examples

Provide real-world, actionable examples that users can copy and modify. Include:

- CLI usage examples covering the common configurations for this server, including security configurations
- Complete Kubernetes manifests with proper YAML formatting
- UI configuration guidance focusing on unique features
- Sample prompts that demonstrate real use cases for the MCP server
- Security-focused examples using network isolation and permission profiles

## Reference existing guides

- Use `docs/toolhive/guides-mcp/_template.mdx` as the reference for exact structure.
- Use existing guides as reference for tone and depth of coverage. A good example is `docs/toolhive/guides-mcp/github.mdx`.

## Quality assurance

Before finalizing, verify that:

- All code examples are syntactically correct
- Configuration parameters match the actual MCP server requirements
- Links to external resources are valid and current
- The guide follows the established template structure
- Examples work with current ToolHive versions

## Content structure requirements

1. **Overview section**: Provide a clear, concise explanation of the MCP server's purpose and key features. Include links to official documentation and highlight what makes this server unique.

2. **Usage section tabs**:

   Using the MCP server's documentation as reference, use its unique features and use cases to create detailed instructions for each tab:
   - **UI tab**: Focus on unique configuration options and features, not basic registry selection. The ToolHive UI includes a configuration interface that allows users to set the secrets and environment variables defined in the server metadata, customize command-line arguments, and add volume mounts. Provide step-by-step instructions for these configurations if needed for the MCP server.
   - **CLI tab**: Provide examples covering the common configurations, including security configurations.
   - **Kubernetes tab**: Include complete, working YAML manifests with proper formatting and comments.

3. **Sample prompts**: Create 3-6 realistic prompts that demonstrate the server's capabilities. Make them specific and actionable, not generic.

4. **Recommended practices**: Focus on security, performance, and reliability best practices specific to the MCP server.