Advanced Workflow: Slash Command to MCP Server via Hook

Hello! Welcome back to our exploration of advanced Claude Code workflows.

In the previous lesson, we created a conceptual map, identifying which advanced features to use at each stage of the development lifecycle. We saw how slash commands, hooks, and MCP servers could orchestrate a full-stack feature implementation from planning to deployment.

Today, we transition from mapping to architectural design. Your goal is to design a complex workflow where a custom slash command triggers a process involving a hook and a custom MCP server. We will blueprint a practical, integrated system that leverages your expertise in FastAPI and PostgreSQL, laying the groundwork for hands-on implementation in our next session.

The Anatomy of an Integrated Workflow

Before we design our own, let's solidify our understanding of the three core components and their distinct roles. Each serves a unique purpose, and their power comes from how they interoperate.

• Slash Command (/): The explicit trigger. This is the user-facing entry point. You decide when to run it, providing clear intent and initiating a defined process.
• MCP Server (mcp__): The external capability provider. It gives Claude access to tools and data outside its core functions, like your database, a third-party API, or a custom microservice.
• Hook (settings.json): The automated guardian. It runs implicitly in response to lifecycle events (like a tool being used). Hooks enforce rules, run quality checks, and automate repetitive tasks without you or Claude having to remember.

These components form a powerful triad: the command expresses intent, the MCP provides capability, and the hook ensures compliance.

Designing a Real-World Workflow

Let's design a workflow tailored to your background. Imagine you're working on one of your GenAI projects that uses FastAPI and PostgreSQL, possibly for a RAG pipeline. A common task is to add new data structures.

Our Goal: Create a robust workflow to scaffold a new database-backed data model.

The workflow will perform three actions:

1. Trigger: A user invokes a /new-model slash command.
2. Action: Claude scaffolds a new Pydantic model and a corresponding SQLAlchemy table model.
3. Integration & Guardrails:
   • The creation event is logged to an external audit service (a custom FastAPI MCP server).
   • A hook prevents any accidental edits to a protected, core database schema file.

Let's design each component.

1. The Auditing MCP Server

First, we need the external capability: a service to log schema changes. This is a perfect use case for a simple, custom MCP server built with FastAPI.

• Functionality: A single API endpoint, say POST /log, that accepts a JSON body like {"event_type": "schema_change", "details": "..."}. In a real system, this might write to a database or a log aggregator. For our design, we can assume it just prints the received data to the console.
• MCP Registration: This FastAPI application would be registered in the project's .claude/mcp.json file. Claude Code would start this server in the background.
• Tool Exposure: Once registered, the server would expose a tool to Claude. Following the standard naming convention, it might be called mcp__audit__log. When Claude uses this tool, it's making an HTTP request to our FastAPI server.

This design gives Claude a new, well-defined capability: mcp__audit__log.

2. The /new-model Slash Command

This is the user's entry point. It's a Markdown file, likely located at .claude/commands/new-model.md.

• Arguments: It needs to accept the name of the new model, which we can capture using the $ARGUMENTS placeholder. For example: /new-model UserFeedback.
• Prompt Design: The core of the command is its prompt, which instructs Claude on the sequence of actions to perform. It would look something like this:

---
description: "Scaffolds a new Pydantic/SQLAlchemy model and logs the event."
argument-hint: "[ModelName]"
---

You are an expert FastAPI developer. Based on the provided model name, `$ARGUMENTS`, perform the following steps:

1.  **Create Pydantic Model:** Generate a Pydantic model for `$ARGUMENTS`. Place it in a new file at `app/schemas/$ARGUMENTS_lower.py`.
2.  **Create SQLAlchemy Model:** Generate a corresponding SQLAlchemy model that inherits from our declarative base. Place it in a new file at `app/models/$ARGUMENTS_lower.py`.
3.  **Log the Event:** Use the `mcp__audit__log` tool to record this action. The tool input should be a JSON object with the format: `{"event_type": "MODEL_CREATE", "model_name": "$ARGUMENTS"}`.
4.  **Confirm:** Report back to me when all steps are complete.

This command design is explicit, multi-step, and integrates the use of our custom MCP tool.

3. The PreToolUse Security Hook

Finally, we need our automated guardian. We want to protect a critical file, for example, app/db/base.py, which might contain the core declarative_base or database session setup. No automated process should ever touch this file.

• Configuration: This hook will be defined in .claude/settings.json.
• Event: It will trigger on the PreToolUse event, which fires before a tool like Edit or Write is executed.
• Matcher: The matcher will target the Edit and Write tools: "matcher": "Edit|Write".
• Logic (The Hook Script): The hook will be a simple shell script.
  1. It reads the JSON input provided by Claude Code via stdin.
  2. It extracts the file_path from the tool's input.
  3. It checks if file_path matches our protected file (app/db/base.py).
  4. If it matches, the script prints an error message to stderr and exits with code 2. This special exit code signals to Claude Code to block the tool's execution.
  5. If it doesn't match, the script exits with code 0, allowing the action to proceed.

To understand the mechanics of hooks and their integration with MCPs, the "Claude Code Hooks" guide is invaluable.

The Complete Workflow in Action

Let's trace the execution flow of our designed system.

Successful Scenario: /new-model UserProfile

1. User: Types /new-model UserProfile.
2. Claude Code: Executes the slash command's prompt.
3. Claude (AI): Generates code for UserProfile and proposes to Write the file app/schemas/user_profile.py.
4. Hook (PreToolUse): The hook script runs. It checks the path app/schemas/user_profile.py, finds no match with the protected file, and exits 0 (allow).
5. Claude Code: The Write operation succeeds.
6. Claude (AI): Proposes to Write the file app/models/user_profile.py.
7. Hook (PreToolUse): The hook runs again, allows the action. The Write operation succeeds.
8. Claude (AI): Proposes to call the mcp__audit__log tool with the payload {"event_type": "MODEL_CREATE", "model_name": "UserProfile"}.
9. Hook (PreToolUse): The hook runs. The tool name (mcp__audit__log) does not match the Edit|Write matcher, so the hook takes no action and implicitly allows it.
10. Claude Code (MCP): Forwards the request to the running FastAPI audit server.
11. FastAPI Server: Receives the request, logs the event, and returns a success response.
12. Claude (AI): Confirms to the user that both models were created and the action was logged.

Failure Scenario: "Add a comment to app/db/base.py"

1. User: Prompts Claude to edit the protected file.
2. Claude (AI): Proposes to Edit the file app/db/base.py.
3. Hook (PreToolUse): The hook script runs. It finds that app/db/base.py matches the protected path.
4. Hook Script: Prints "ERROR: app/db/base.py is a protected file and cannot be modified." to stderr and exits 2 (block).
5. Claude Code: The Edit operation is blocked.
6. Claude (AI): Receives the error message from the hook and informs the user: "I cannot perform this action because app/db/base.py is a protected file."

This design creates a powerful, semi-autonomous workflow that is both efficient and safe.

Conclusion

Today, we've moved from theory to practice by architecting a concrete, integrated workflow. We designed a system where a user's explicit intent (a slash command) triggers a series of actions that leverage an external capability (an MCP server), all while being governed by automated safety rules (a hook).

Key Takeaways:

• Design is about Interconnection: The power lies not in the individual components, but in how they are designed to communicate and trigger one another.
• Command as the Entry Point: Slash commands are the ideal way to start a complex, predefined workflow, passing initial parameters.
• MCP for Extensibility: Custom MCP servers are the bridge to your existing infrastructure, allowing Claude to interact with your databases, APIs, and services in a structured way.
• Hooks for Safety and Automation: PreToolUse hooks are essential for creating programmable guardrails that enforce project rules deterministically, making autonomous workflows safer.

Next Up:

With our architectural blueprint complete, the next logical step is to build it. In our next lesson, you will implement and debug this integrated workflow, writing the Python code for the FastAPI MCP server, the shell script for the hook, and the Markdown/YAML for the slash command. You'll see firsthand how these designed components come together in a functioning system.