Usage guide

A comprehensive guide to PatternFly MCP Server tools, resources, and configuration.

User Guide:

Built-in tools
Built-in resources
MCP client configuration
Running via container
Custom MCP tool plugins
Experimental settings
Troubleshooting

Built-in tools

MCP tools represent the actions available to interact with the server.

Core server tools provide a resource library for PatternFly. They are extensible by design and intended for use with available MCP resources.

Tool: searchPatternFlyDocs

Use this to search for PatternFly documentation URLs, patternfly:// resource URIs, and component names. Accepts partial string matches or * to list all available components. From the content, you can select specific URLs, URIs, and component names to use with usePatternFlyDocs.

Transitional URI support: The default tools also return and accept patternfly:// URIs for compatibility. Using and passing URIs through these tools is supported as a compatibility bridge for the intended workflow; see experimental context management for details on the transitional allowance for limited MCP clients.

Parameters:

searchQuery: string (required) - Full or partial component name to search for (e.g., "button", "table", "*" for all components)

Example:

{
  "searchQuery": "button"
}

Tool: usePatternFlyDocs

Fetch full documentation and component JSON schemas for specific PatternFly URLs, patternfly:// URIs, or component names.

Feature: This tool automatically detects if a URL belongs to a component (or if a "name" is provided) and appends its machine-readable JSON schema (props, types, validation) to the response, combining human-readable documentation with technical specifications.

Parameters: Parameters are mutually exclusive. Provide either name OR urlList, not both.

name: string (optional) - A PatternFly component or resource name (e.g., "Button", "Modal"), or a patternfly:// URI (e.g., "patternfly://docs/button"). Names are recommended for known component lookups.
urlList: string[] (optional) - A list of documentation URLs and/or patternfly:// URIs from searchPatternFlyDocs (max 15 at a time).

Transitional URI support: Prefer reading patternfly:// URIs with MCP resources/read when your client supports it. Passing URIs through this tool is supported as a compatibility bridge for the intended workflow; see experimental context management for details on the transitional allowance for limited MCP clients.

Example with name:

{
  "name": "Button"
}

Example with urlList:

{
  "urlList": ["https://patternfly.org/components/button"]
}

Deprecated tools

Tool: fetchDocs (Removed)

"fetchDocs" has been integrated into "usePatternFlyDocs."

Tool: componentSchemas (Removed)

"componentSchemas" has been integrated into "usePatternFlyDocs" and MCP resources.

Built-in resources

MCP resources represent indexed collections of documentation and machine-readable metadata.

The server exposes a resource-centric architecture via the patternfly:// URI scheme. MCP clients can use these resources directly. Review the roadmap for future resource updates.

Note on AI content: Specialized AI guidance resources are sourced from the patternfly/ai-helpers integration. These are specifically optimized to help LLMs generate more accurate PatternFly code. See Data sources and integrations in architecture.

Discovery resources

Use these indexes to discover what is available in the library:

patternfly://docs/index{?version,category,section}: A comprehensive index of all available PatternFly documentation pages.
patternfly://docs/meta{?version}: Metadata discovery for available PatternFly documentation pages, helpful for understanding available filter parameters.
patternfly://components/index{?version,category}: A list of all available PatternFly component names.
patternfly://components/meta{?version}: Metadata discovery for components, helpful for understanding available filter parameters.
patternfly://schemas/index{?version,category}: An index of all available component JSON schemas.
patternfly://schemas/meta{?version}: Metadata discovery for JSON schemas, helpful for understanding available filter parameters.

Component and documentation resources

Access specific component documentation or technical specifications using the following URI templates (RFC 6570):

patternfly://docs/{name}{?version,category,section}: Full human-readable documentation for a specific component (e.g., patternfly://docs/button) or guideline.
patternfly://schemas/{name}{?version,category}: Machine-readable JSON Schema for a specific component, detailing props, types, and validation rules (e.g., patternfly://schemas/button).

Context and guidelines

patternfly://context: General PatternFly MCP server context, including high-level development rules and accessibility guidelines.

Tip for LLMs: When a user asks about a component you aren't familiar with, first check patternfly://docs/index to find the correct name, then read the documentation via patternfly://docs/{name}. Use patternfly://components/index for a cleaner list of component-only names.

MCP client configuration

Most MCP clients use JSON configuration to specify how the server is started. Below are examples you can adapt for your client.

Pinned MCP package version

Depending on your environment, you may have to delay updating to the minimum Node.js version required by the server. If you are unable to upgrade your Node.js version and must remain on a previous Node.js version, you can pin your MCP configuration to the last compatible version of the server.

Note: Currently, pinning to an older PatternFly MCP version means you will not receive updated documentation or new features until you "update" your pinned version. In the future, pinning a version may still make an allowance for documentation updates. See our planned architecture.

When to choose `@latest` or a pinned version for configuration

Node.js version	Package spec	Feature notes
>=22	`@patternfly/patternfly-mcp@latest`	Newest PatternFly features and rules. Includes enhanced security isolation for custom tool plugins.
>=20	`@patternfly/patternfly-mcp@1.1.0`	Standard features and rules. Lacks custom tool plugins; compatible with all default PatternFly configurations.

Node.js 20 compatible pin

{
  "mcpServers": {
    "patternfly-mcp": {
      "command": "npx",
      "args": ["-y", "@patternfly/patternfly-mcp@1.1.0"],
      "description": "PatternFly rules and documentation (Node.js 20 compatible)"
    }
  }
}

Minimal client config (stdio)

{
  "mcpServers": {
    "patternfly-mcp": {
      "command": "npx",
      "args": ["-y", "@patternfly/patternfly-mcp@latest"],
      "description": "PatternFly rules and documentation"
    }
  }
}

HTTP transport mode

{
  "mcpServers": {
    "patternfly-mcp": {
      "command": "npx",
      "args": ["-y", "@patternfly/patternfly-mcp@latest", "--http", "--port", "8080"],
      "description": "PatternFly rules and documentation (HTTP transport)"
    }
  }
}

Custom local tool

{
  "mcpServers": {
    "patternfly-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@patternfly/patternfly-mcp@latest",
        "--tool",
        "./mcp-tools/local-custom-tool.js"
      ],
      "description": "PatternFly MCP with a local custom tool"
    }
  }
}

HTTP mode with security

{
  "mcpServers": {
    "patternfly-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@patternfly/patternfly-mcp@latest",
        "--http",
        "--port",
        "3000",
        "--allowed-origins",
        "https://app.com",
        "--allowed-hosts",
        "localhost,127.0.0.1"
      ],
      "description": "PatternFly rules and documentation (HTTP transport with security)"
    }
  }
}

Running via container (podman)

The server can also be launched from a container image instead of npx. This is useful when you want a pinned, sandboxed runtime that doesn't depend on the host's Node.js installation. Running with an MCP client spawns podman (or docker) instead of npx.

Prerequisites: podman is the supported container runtime for PatternFly MCP. We recommend podman desktop or podman.

We make a minimal effort to support Docker, and additional configuration may be required.

Build the image locally

From the repository root:

bash ./scripts/container.build.sh

or using Node.js and NPM:

npm run container:build

This produces the following images:

localhost/patternfly-mcp:<version>,
localhost/patternfly-mcp:<version>-node24,
localhost/patternfly-mcp:sha-<short>
localhost/patternfly-mcp:latest.

You can confirm by running $ podman images from the terminal. View the Containerfile for the image definition.

Running your local image, MCP client configuration

{
  "mcpServers": {
    "patternfly-mcp": {
      "command": "podman",
      "env": {
        "PODMAN_USERNS": "keep-id"
      },
      "args": [
        "run",
        "--rm",
        "-i",
        "--security-opt=no-new-privileges",
        "--cap-drop=ALL",
        "localhost/patternfly-mcp:latest",
        "--log-stderr"
      ],
      "description": "PatternFly rules and documentation (local container)"
    }
  }
}

Important:

-i (interactive stdin) is required for stdio MCP. Do not pass -t. Anything appended after the image name is forwarded verbatim to the CLI, so every flag (--verbose, --http, --port, --tool, ...) works without rebuilding.

If you're attempting to run the same configuration with Docker, you'll need to make at least one adjustment:

Replace "command": "podman" with "command": "docker".

On podman, PODMAN_USERNS replaces --userns=keep-id. If you come across the --userns=keep-id flag, and you are using Docker, remove it.

Smoke test

podman run --rm --entrypoint node localhost/patternfly-mcp:latest -e "console.log(process.versions.node)"  # -> 24.x

Running in HTTP transport mode

The image's ENTRYPOINT forwards every argument straight to the CLI, so HTTP mode works against the same image with no rebuild — just publish a port and pass --http --port.

podman run --rm \
  --userns=keep-id \
  --security-opt=no-new-privileges \
  --cap-drop=ALL \
  --read-only \
  --tmpfs /tmp:rw,size=64m \
  -p 3030:8080 \
  localhost/patternfly-mcp:latest \
  --http \
  --port 8080 \
  --allowed-origins "http://127.0.0.1:3030" \
  --allowed-hosts  "127.0.0.1" \
  --log-stderr

Notes:

-p <host>:<container> publishes the port. The container-side port (8080 above) must match --port. The host-side port is whatever you want clients to connect to.
8080 inside the container matches the port the UBI Node.js base already advertises via EXPOSE, and a non-root user can bind it without extra capabilities.
-i (interactive stdin) is not required in HTTP mode and is omitted here.
--allowed-origins and --allowed-hosts are required guardrails when the server is reachable beyond stdio; set them explicitly.
--read-only is safe today because the server writes nothing to the rootfs (only /tmp, which is a tmpfs). When the persistent SQLite cache lands, you will need to either drop --read-only or mount a writable volume for the cache directory.
TLS is out of scope for the image itself. For anything beyond localhost, terminate TLS at a reverse proxy (Caddy, nginx, an OpenShift route, etc.).

MCP client configuration (HTTP)

HTTP MCP clients connect via URL rather than spawning a process. Start the container separately (e.g. with the command above, podman-compose, or a systemd unit) and point the client at the published host port:

{
  "mcpServers": {
    "patternfly-mcp": {
      "url": "http://localhost:3030",
      "description": "PatternFly rules and documentation (HTTP transport, containerized)"
    }
  }
}

Stdio-only MCP clients should keep using the stdio container configuration above; the HTTP form requires a client that supports HTTP/SSE MCP transports.

Verify it's listening

curl -sS -i http://localhost:3030/ | head -20

--log-stderr will print the registered routes at startup, which is the easiest way to confirm the server bound the expected port.

Custom MCP tool plugins

You can extend the server's capabilities by loading custom Tool Plugins at startup.

See development documentation for tool plugins.

Troubleshooting

These are first-step checks for common setup problems, not full diagnostics. If something still fails, use the community links at the end of this section or ask your IT team, especially on Windows, where permissions, security software, and Git setup vary and may be beyond simple troubleshooting.

Note on Operating Systems: Our primary development and testing environments are macOS and Linux. While we provide instructions for Windows, these commands are run at your own discretion. If you are unsure, please verify them with your IT or system administrator before proceeding.

Agents: PatternFly MCP server information is available internally through the patternfly://context MCP resource.

1. Verify Node.js version

The PatternFly MCP server requires Node.js 22 or higher.

How to check:
- macOS/Linux: Open Terminal and type node -v.
- Windows: Open PowerShell or Command Prompt and type node -v.
Requirement: You should see a version starting with v22, or higher.
Solution: If your version is lower than 22, please download and install the latest "LTS" (Long Term Support) version from nodejs.org.

Unable to update your Node.js version? See pinned configuration examples for earlier Node.js versions.

2. Reset the npx Cache

If you encounter an ERR_MODULE_NOT_FOUND error or don't see the latest features, your system may be using a "stale" or corrupted version in its cache.

macOS and Linux

Run this command in your Terminal:

rm -rf ~/.npm/_npx

Windows

Run the appropriate command for your terminal:

PowerShell:

Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"

Command Prompt (CMD):

rd /s /q "%LocalAppData%\npm-cache\_npx"

Next Step: Restart your MCP client (e.g., Claude Desktop, IDE, or Cursor) to force a fresh download.

3. Windows-Specific: Symbolic Links

On Windows, folders such as .agents/skills and .claude/skills can look empty if Git created them as normal folders instead of links to guidelines/skills. This often happens because Developer Mode, or Git symlink support, hasn't been enabled.

For detailed instructions on enabling and restoring symlinks, please refer to the Windows and repository symlinks section in CONTRIBUTING.md.

4. Configuration Best Practices

To ensure you stay up to date with the latest PatternFly documentation, use the @latest tag in your configuration:

"patternfly-mcp": {
  "command": "npx",
  "args": ["-y", "@patternfly/patternfly-mcp@latest"],
  "description": "PatternFly rules and documentation"
}

Using @latest in the configuration means installs resolve to the "latest" published version when npm/npx fetches the package, typically on a new npx run.

5. Common Error: `ERR_MODULE_NOT_FOUND`

If your logs show Error [ERR_MODULE_NOT_FOUND], it likely indicates a corrupted cache following a PatternFly MCP version update. Please follow the Reset the npx Cache steps above for your specific operating system.

6. Community Support

If you have tried the steps above and are still encountering issues, or if you have specific questions about using PatternFly with your AI assistant, the following community resources are available:

PatternFly Slack: Join our Slack community for real-time support and conversation.
GitHub Discussions: A great place to ask questions, share ideas, and see how others are leveraging PatternFly.
PatternFly on Medium: Read articles and deep-dives into PatternFly design and development practices.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Usage guide

Built-in tools

Tool: searchPatternFlyDocs

Tool: usePatternFlyDocs

Deprecated tools

Tool: fetchDocs (Removed)

Tool: componentSchemas (Removed)

Built-in resources

Discovery resources

Component and documentation resources

Context and guidelines

MCP client configuration

Pinned MCP package version

When to choose `@latest` or a pinned version for configuration

Node.js 20 compatible pin

Minimal client config (stdio)

HTTP transport mode

Custom local tool

HTTP mode with security

Running via container (podman)

Build the image locally

Running your local image, MCP client configuration

Smoke test

Running in HTTP transport mode

MCP client configuration (HTTP)

Verify it's listening

Custom MCP tool plugins

Troubleshooting

1. Verify Node.js version

2. Reset the npx Cache

macOS and Linux

Windows

3. Windows-Specific: Symbolic Links

4. Configuration Best Practices

5. Common Error: `ERR_MODULE_NOT_FOUND`

6. Community Support

Uh oh!

FilesExpand file tree

usage.md

Latest commit

History

usage.md

File metadata and controls

Usage guide

Built-in tools

Tool: searchPatternFlyDocs

Tool: usePatternFlyDocs

Deprecated tools

Tool: fetchDocs (Removed)

Tool: componentSchemas (Removed)

Built-in resources

Discovery resources

Component and documentation resources

Context and guidelines

MCP client configuration

Pinned MCP package version

When to choose @latest or a pinned version for configuration

Node.js 20 compatible pin

Minimal client config (stdio)

HTTP transport mode

Custom local tool

HTTP mode with security

Running via container (podman)

Build the image locally

Running your local image, MCP client configuration

Smoke test

Running in HTTP transport mode

MCP client configuration (HTTP)

Verify it's listening

Custom MCP tool plugins

Troubleshooting

1. Verify Node.js version

2. Reset the npx Cache

macOS and Linux

Windows

3. Windows-Specific: Symbolic Links

4. Configuration Best Practices

5. Common Error: ERR_MODULE_NOT_FOUND

6. Community Support

When to choose `@latest` or a pinned version for configuration

5. Common Error: `ERR_MODULE_NOT_FOUND`