Civic MCP Hooks

A middleware layer for the Model Context Protocol (MCP) that enables monitoring, validation, and transformation of AI tool interactions.

Understanding MCP and Why It Needs Hooks

What is MCP?

The Model Context Protocol (MCP) is a standard that allows AI assistants (like Claude) to interact with external tools and services. Think of it as a universal language that lets AI models:

• Read and write files
• Query databases
• Call APIs
• Execute code
• Access various services

When you use an AI assistant with MCP, it can perform real actions on your behalf, making it incredibly powerful for automation and productivity.

Why Add a Middleware Layer?

While MCP's power is exciting, it also raises important questions:

• Security: How do we ensure the AI only accesses what it should?
• Auditing: How do we track what actions were taken?
• Control: How do we prevent unintended or dangerous operations?
• Customization: How do we modify behavior for specific use cases?

This is where hooks come in. Just like web applications use middleware to handle authentication, logging, and request processing, MCP can benefit from a similar pattern.

How This Solution Works

Our approach introduces a "passthrough server" that sits between the AI and the actual MCP tools:

AI Assistant ←→ Passthrough Server ←→ Target MCP Server
                       ↓↑
                    [Hooks]

Here's what happens when the AI wants to use a tool:

1. Request:  AI → Passthrough → Hook 1 → Hook 2 → ... → Target MCP Server
2. Response: AI ← Passthrough ← Hook 2 ← Hook 1 ← ... ← Target MCP Server

The passthrough server:

1. Intercepts all requests from the AI
2. Processes them through a chain of hooks
3. Forwards approved requests to the actual tool
4. Returns the response (also processed through hooks)

Each hook in the chain can:

• Inspect the request (What is the AI trying to do?)
• Modify the request (Change parameters, add context)
• Approve or Reject the request (Security and validation)
• Perform side effects (Audit logging, notifications, analytics)
• Transform the response (Format, filter, or enhance results)

Real-World Examples

Why do we need MCP-specific hooks? It's about separation of concerns and the unique challenges of LLM tool use.

The Core Problem: MCP servers are designed to do one thing well - provide tools. They shouldn't be cluttered with authentication logic, audit trails, or context-specific modifications. Additionally, OAuth (which MCP uses) lacks the granularity needed for LLM interactions - there's no way to express "allow file reads but only in the /docs folder" or "allow API calls but rate-limit based on content."

Example 1: LLM-Specific Guardrails

Your MCP file server provides simple file operations. But LLMs need different rules than human users:

Human user: Can precisely click on files they need
LLM: Might try to read entire directory trees to "be helpful"

Guardrail Hook: Limits directory traversal depth, prevents reading 
binary files, and caps file sizes - rules that only make sense for LLMs

The MCP server stays simple, while the hook adds LLM-specific safety rails.

Example 2: Context-Dependent Tool Descriptions and Prompts

The same tool might need different descriptions for different use cases:

Standard fetch tool: "Retrieves web content"

In a research environment:
"Retrieves web content (academic sources preferred, checks Sci-Hub)"

In a corporate environment:
"Retrieves web content (internal wiki only, external sites blocked)"

The Custom Description Hook modifies tool descriptions based on your context - something the original MCP server can't and shouldn't handle.

Example 3: Forcing Transparency with Explain Hook

LLMs can use tools without explaining why. The Explain Hook adds a required "reason" parameter:

Without hook:
AI: execute_sql("DROP TABLE users")

With Explain Ho

... [View full README on GitHub](https://github.com/civicteam/mcp-hooks#readme)