# How the ponytail-mcp Server Complements Always-On Hook Adapters in DietrichGebert/ponytail

> Discover how the ponytail-mcp server complements always-on hook adapters by exposing the Ponytail instruction set via MCP prompts for hosts like Claude Desktop and Codex.

- Repository: [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail)
- Tags: how-to-guide
- Published: 2026-09-12

---

**The `ponytail-mcp` server exposes Ponytail's lazy-senior-dev instruction set via Model Context Protocol (MCP) prompts and tools, allowing hosts like Claude Desktop and Codex to access the same ruleset as always-on hook adapters when persistent injection points are unavailable.**

The DietrichGebert/ponytail repository provides multiple integration strategies for enforcing consistent coding standards across LLM interactions. While always-on hook adapters offer seamless automation for supported platforms, the `ponytail-mcp` server fills a critical gap for MCP-only environments by delivering identical instructions through an on-demand protocol.

## How Always-On Hook Adapters Work

Always-on hook adapters integrate directly into a host's runtime to inject the Ponytail ruleset automatically on every LLM turn. These adapters rely on persistent "hook" integrations that modify the context window before each inference.

For example, the Claude hooks implementation in [`hooks/claude-codex-hooks.json`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/claude-codex-hooks.json) and the Pi extension in [`hooks/ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js) capture the instruction set from [`hooks/ponytail-instructions.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-instructions.js) and prepend it to every conversation turn without user intervention. This approach ensures that **every response** adheres to the configured mode—whether `lite`, `full`, or `ultra`—because the hook is permanently embedded in the host's execution environment.

However, not all LLM hosts support such deep integration. Platforms like Claude Desktop, Codex CLI, and Pi often restrict third-party code from modifying the runtime directly, making always-on hooks impossible to deploy.

## The MCP Server Bridge for Restricted Environments

The `ponytail-mcp` server complements these always-on adapters by providing a clean, portable entry point for hosts that only support MCP-based context injection. Instead of requiring a persistent hook, the server exposes the Ponytail ruleset through standardized MCP endpoints: a prompt named `ponytail` and a tool called `ponytail_instructions`.

In [`ponytail-mcp/index.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-mcp/index.js), the server registers these capabilities using the Model Context Protocol SDK. When an MCP client connects, it can request the instructions on demand by invoking the prompt or tool, rather than receiving them automatically through a runtime hook. This architecture makes Ponytail available to any MCP-compatible host, regardless of whether it supports always-on injection.

## Shared Logic Ensures Consistent Behavior

What makes the `ponytail-mcp` server a true complement rather than a replacement is its reuse of the exact same instruction-building pipeline. Both the always-on hooks and the MCP server rely on [`hooks/ponytail-instructions.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-instructions.js) to filter the skill file according to the active mode.

The server resolves the effective mode using [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js), which checks for user preferences in `~/.config/ponytail/config.json`. This guarantees that a developer using `lite` mode in their always-on Claude hook will receive identical instructions when calling the `ponytail_instructions` tool from an MCP client. The [`ponytail-mcp/instructions.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-mcp/instructions.js) file handles this resolution, bridging the MCP request to the shared builder logic.

## Setting Up and Using the ponytail-mcp Server

To deploy the MCP server and connect it to an MCP client, install the dependencies and launch the process:

```bash

# Start the MCP server from the repository root

cd ponytail-mcp
npm install        # install the @modelcontextprotocol SDK

node index.js      # launches the MCP server on stdio

```

Configure your MCP client to discover the server by adding it to your client configuration:

```json
{
  "mcpServers": {
    "ponytail": {
      "command": "node",
      "args": ["ponytail-mcp/index.js"]
    }
  }
}

```

Once connected, clients can consume the prompt directly:

```javascript
// Consuming the prompt from an MCP-enabled client
await client.sendPrompt("ponytail", { mode: "lite" });

```

Or retrieve structured instructions programmatically:

```javascript
// Consuming the tool to get structured instructions
const { mode, instructions } = await client.runTool(
  "ponytail_instructions", 
  { mode: "full" }
);

```

## Summary

- **The `ponytail-mcp` server provides a protocol-based alternative** to always-on hooks for MCP-compatible hosts like Claude Desktop and Codex.
- **Both integration methods share identical instruction logic** through [`hooks/ponytail-instructions.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-instructions.js) and configuration resolution in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js).
- **Mode consistency is preserved** across platforms, respecting user defaults stored in `~/.config/ponytail/config.json`.
- **The server exposes two primary interfaces**: a `ponytail` prompt for quick access and a `ponytail_instructions` tool for programmatic retrieval.
- **Complementary architecture** ensures developers can use always-on hooks where available and fall back to MCP where hooks are restricted.

## Frequently Asked Questions

### What is the difference between always-on hooks and the ponytail-mcp server?

Always-on hooks modify the host runtime to inject instructions automatically on every turn, requiring deep integration support. The `ponytail-mcp` server exposes the same instructions through Model Context Protocol endpoints, requiring the user or client to explicitly request them via prompts or tools. Both ultimately source their content from [`hooks/ponytail-instructions.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-instructions.js), ensuring identical output.

### Can I use both always-on hooks and the MCP server simultaneously?

Yes. Both systems read from the same configuration files and instruction builders. If you have always-on hooks active in one environment (e.g., a custom Claude integration) and use the MCP server in another (e.g., Claude Desktop), your default mode and instruction set remain synchronized through [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js) and the shared resolution logic.

### How does the MCP server determine which mode to use?

The server delegates mode resolution to [`ponytail-mcp/instructions.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-mcp/instructions.js), which imports the configuration logic from [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js). This module checks the active environment and falls back to `~/.config/ponytail/config.json` to determine whether to use `lite`, `full`, or `ultra` mode, ensuring your personal defaults are respected across all integration types.

### Which LLM hosts require the MCP server instead of always-on hooks?

Hosts that do not expose a runtime hook or extension API—such as standard Claude Desktop, Codex CLI, and Pi—cannot embed the always-on adapters found in [`hooks/claude-codex-hooks.json`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/claude-codex-hooks.json) or [`hooks/ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js). These platforms rely on the Model Context Protocol for third-party context, making the `ponytail-mcp` server the only viable integration path for accessing Ponytail instructions.