# Usage guide

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

**User Guide:**
- [Built-in tools](#built-in-tools)
- [Built-in resources](#built-in-resources)
- [MCP client configuration](#mcp-client-configuration)
- [Running via container](#running-via-container-podman)
- [Custom MCP tool plugins](#custom-mcp-tool-plugins)
- [Experimental settings](./experimental.md)
- [Troubleshooting](#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](./experimental.md#contextmanagement) 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:**
```json
{
  "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](./experimental.md#contextmanagement) for details on the transitional allowance for limited MCP clients.

**Example with name:**
```json
{
  "name": "Button"
}
```

**Example with urlList:**
```json
{
  "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](./architecture.md#roadmap).

> **Note on AI content**: Specialized AI guidance resources are sourced from the [patternfly/ai-helpers](https://github.com/patternfly/ai-helpers) integration. These are specifically optimized to help LLMs generate more accurate PatternFly code. [See Data sources and integrations in architecture](./architecture.md#data-sources-and-integrations).

### 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.](./architecture.md#library-synchronization-in-progress) 

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

```json
{
  "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)

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

### HTTP transport mode

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

### Custom local tool

```json
{
  "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

```json
{
  "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](https://podman-desktop.io/downloads) or [podman](https://podman.io/).
>
> We make a minimal effort to support Docker, and additional configuration may be required.

#### Build the image locally

From the repository root:

```bash
bash ./scripts/container.build.sh
```

or using Node.js and NPM:

```sh
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](../Containerfile) for the image definition.

#### Running your local image, MCP client configuration

```json
{
  "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

```bash
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`.

```bash
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:

```json
{
  "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](#running-your-local-image-mcp-client-configuration); the HTTP form requires a client that supports HTTP/SSE MCP transports.

##### Verify it's listening

```bash
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.](./development.md#mcp-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](https://nodejs.org/).

> **Unable to update your Node.js version?** [See pinned configuration examples for earlier Node.js versions.](#pinned-mcp-package-version)

### 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**:
```bash
rm -rf ~/.npm/_npx
```

#### **Windows**
Run the appropriate command for your terminal:
- **PowerShell**:
  ```powershell
  Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"
  ```
- **Command Prompt (CMD)**:
  ```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](../CONTRIBUTING.md#windows-and-repository-symlinks)**.

### 4. Configuration Best Practices
To ensure you stay up to date with the latest PatternFly documentation, use the `@latest` tag in your configuration:

```json
"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](#2-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](https://patternfly.slack.com/)**: Join our Slack community for real-time support and conversation.
- **[GitHub Discussions](https://github.com/orgs/patternfly/discussions)**: A great place to ask questions, share ideas, and see how others are leveraging PatternFly.
- **[PatternFly on Medium](https://medium.com/patternfly)**: Read articles and deep-dives into PatternFly design and development practices.