AI Integration (MCP Server)

What is the MCP Server?

The Model Context Protocol (MCP) server enables reliable integration between Clay and AI assistants. It provides type-safe, validated tool calls that eliminate parameter hallucination and errors.

Benefits

• ✅ Type-safe tool calls - no hallucinated parameters
• ✅ Direct access to all Clay operations
• ✅ Automatic validation before execution
• ✅ Discover available Handlebars helpers on-demand
• ✅ Test JSONPath expressions interactively
• ✅ Zero-parameter operations (regenerate everything with one call)
• ✅ Built-in prompts for learning Clay architecture and workflows

Available Tools

The MCP server provides 14 tools:

Project & Generation

• clay_generate - Generate code from models
• clay_clean - Clean up generated files
• clay_test_path - Test JSONPath expressions
• clay_init - Initialize projects or generators
• clay_list_generators - List all generators
• clay_get_model_structure - Inspect model structure
• clay_list_helpers - List Handlebars helpers with examples
• clay_explain_concepts - Get comprehensive documentation

Model CRUD (include-aware)

These tools let the AI query and modify your model data directly. They are include-aware: they query the expanded model (with includes resolved) to find targets, then trace back to the correct source file to apply the edit. If data lives in an included file, the mutation is written there — the main model's include reference is preserved.

• clay_model_query - Query model data with JSONPath (searches the expanded model)
• clay_model_add - Add items to arrays or properties to objects
• clay_model_update - Update fields on matched items
• clay_model_delete - Remove matched items (deleting an included entity removes the include reference from the main model)
• clay_model_rename - Rename a property key on matched items
• clay_model_set_schema - Set or update $schema reference on a model

Built-in Prompts

The MCP server includes 2 comprehensive prompts that teach AI assistants about Clay:

• clay-getting-started - Complete guide to Clay architecture, project structure, and using basic tools (clean, generate)
• clay-workflow - Step-by-step workflow from project setup to code generation with real-world examples

These prompts provide instant, comprehensive knowledge to AI assistants, ensuring consistent and accurate guidance when working with Clay projects.

Protecting Generated Files

AI assistants can accidentally edit files that are generated by Clay. Clay provides built-in commands to prevent this.

Claude Code

Claude Code supports hooks that intercept tool calls. Clay can install a PreToolUse hook that blocks Edit/Write operations on any file listed in the .clay manifest:

clay init-claude

This creates .claude/settings.json with a hook that calls clay check-generated before any Edit/Write operation. No scripts are generated — Clay handles the check entirely via the clay binary.

When Claude tries to edit a generated file, the hook blocks the operation and shows a helpful message explaining how to use Clay MCP tools instead.

Commit the .claude/ directory to git so hooks travel with the repo — every team member gets protection automatically.

Adding the MCP Server

Use clay init-mcp to add the Clay MCP server to your AI platform's configuration:

clay init-mcp

This interactively asks which platforms you use (VS Code / Copilot, Claude Code, Claude Desktop, Cursor) and writes the correct config for each. It auto-detects platforms already present in your project and pre-selects them.

Other AI Assistants

For AI assistants without hook support (Cursor, Windsurf, etc.), add instructions to your project's AI configuration file (e.g. .cursorrules) telling the assistant not to edit generated files. Check file headers for "This file is generated using Clay" comments.

Setup for Claude Desktop

1. Install Clay

npm install -g clay-generator

2. Configure Claude

Edit your Claude config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "clay": {
      "command": "clay-mcp",
      "args": []
    }
  }
}

3. Restart Claude Desktop

The MCP server will start automatically when Claude launches.

Setup for VS Code + GitHub Copilot

1. Install Clay

npm install -g clay-generator

2. Create MCP Configuration

Create .vscode/mcp.json in your project:

{
  "servers": {
    "clay": {
      "type": "stdio",
      "command": "clay-mcp",
      "args": []
    }
  }
}

Or use the Command Palette: MCP: Open Workspace Folder Configuration

3. Trust the Server

VS Code will prompt you to trust the server when it starts. You can also manage servers via:

• MCP: List Servers - View all configured servers
• MCP: Start Server - Manually start the Clay server

4. Use in Copilot Chat

Reference Clay tools in Copilot Chat:

# List available helpers
#clay_list_helpers

# Generate code
#clay_generate

# Test a JSONPath
#clay_test_path

Usage Examples

Regenerate All Models

User: "Regenerate all my Clay models"

AI calls: clay_generate({})

Generate Specific Model

User: "Generate code for the users model"

AI calls: clay_generate({ model_path: "./clay/users-model.json", output_path: "./src" })

Test JSONPath

User: "Show me all array-type parameters"

AI calls: clay_test_path({ model_path: "./clay/model.json", json_path: "$.model.types[*].commands[*].parameters[?(@.type=='array')]" })

List Helpers

User: "What Handlebars helpers can I use?"

AI calls: clay_list_helpers({ include_examples: true })

Get Helper by Category

User: "Show me string manipulation helpers"

AI calls: clay_list_helpers({ category: "string", include_examples: true })

Get Specific Helper Examples

User: "How do I use the pluralize helper?"

AI: The AI calls clay_list_helpers({ include_examples: true }) and shows:

{{pluralize "category"}} → categories
{{pluralize "user"}} → users
{{pluralize "child"}} → children

Common helper categories available:

• string: camelCase, pascalCase, kebabCase, snakeCase, upperCase, lowerCase, capitalize, startCase, pluralize, singularize, pad, repeat, replace, truncate, words, split
• comparison: eq, ne, lt, gt, lte, gte
• logic: if, and, or, switch/case, ifCond
• iteration: each, eachUnique, eachUniqueJSONPath, times, group
• type-check: isArray, isString, isNumber, isBoolean, isEmpty, isNull, isUndefined
• utility: json, markdown, inc, includes, startsWith, endsWith, parseInt

Query Model Data

User: "Show me the User entity"

AI calls: clay_model_query({ model_path: "./clay/model.json", json_path: "$.model.entities[?(@.name=='User')]" })

Add a Field to an Entity

User: "Add an email field to the User entity"

AI calls: clay_model_add({ model_path: "./clay/model.json", json_path: "$.model.entities[?(@.name=='User')].fields", value: { name: "email", type: "string" } })

If User lives in an included file (e.g. entities/user.json), the field is added there automatically. The response includes source_file showing which file was modified.

Update an Entity

User: "Add a description to the User entity"

AI calls: clay_model_update({ model_path: "./clay/model.json", json_path: "$.model.entities[?(@.name=='User')]", fields: { description: "A registered user" } })

Delete a Field

User: "Remove the legacy_id field from User"

AI calls: clay_model_delete({ model_path: "./clay/model.json", json_path: "$.model.entities[?(@.name=='User')].fields[?(@.name=='legacy_id')]" })

Rename a Property

User: "Rename 'fields' to 'columns' on all entities"

AI calls: clay_model_rename({ model_path: "./clay/model.json", json_path: "$.model.entities[*]", old_name: "fields", new_name: "columns" })

Learn About Generators

User: "How do I create a generator?"

AI calls: clay_explain_concepts({ topic: "generators", include_examples: true })

Understand Context Variables

User: "What are clay_key and clay_parent?"

AI calls: clay_explain_concepts({ topic: "context-variables" })

AI Workflow Examples

Creating a New Generator

You: "Help me create a REST API generator for my user model"

AI: *Calls clay_get_model_structure to inspect your model*
    *Calls clay_list_helpers to see available helpers*
    *Creates generator.json with appropriate steps*
    *Creates templates using discovered helpers*
    *Calls clay_generate to test the generator*

Editing Models with Includes

You: "Add a 'role' field to the User entity"

AI: *Calls clay_model_query to find the User entity*
    *Calls clay_model_add to add the field*
    *Response shows source_file: "entities/user.json"*
    *The included file was edited, main model unchanged*

Debugging JSONPath

You: "Why isn't my generator selecting the right fields?"

AI: *Calls clay_test_path with your current selector*
    *Analyzes the results*
    *Suggests corrected JSONPath expression*
    *Calls clay_test_path again to verify*

Template Development

You: "I need a template that converts field names to PascalCase"

AI: *Calls clay_list_helpers with category: "string"*
    *Shows you the pascalCase helper*
    *Creates example template using {{pascalCase name}}*

Advanced Helper Usage

You: "Create a template that generates TypeScript types with proper casing"

AI: *Calls clay_list_helpers to review case conversion helpers*
    *Suggests using pascalCase for type names*
    *Suggests using camelCase for property names*
    
Template created:
export type {{pascalCase name}} = {
  {{#each fields}}
  {{camelCase name}}: {{type}};
  {{/each}}
};

Type Checking in Templates

You: "How do I conditionally render based on field types?"

AI: *Calls clay_list_helpers with category: "type-check"*
    *Shows isArray, isString, isNumber, etc.*
    
Template example:
{{#each fields}}
  {{#if (isArray type)}}
    // {{name}} is an array type
  {{else if (isString type)}}
    // {{name}} is a string type
  {{/if}}
{{/each}}

Why No Watch Mode?

The clay watch command is intentionally not included in the MCP server because it's a long-running background process that doesn't fit the MCP request-response model.

Instead:

• Run clay watch directly in a terminal
• Or create a VS Code task to manage the watch process
• The AI can guide you to set this up manually

Troubleshooting

Server Not Starting

Verify Clay is installed globally:

which clay-mcp
# Should show: /usr/local/bin/clay-mcp or similar

Tools Not Appearing

Check the server status in your AI assistant:

• Claude: Look for the 🔌 icon in the chat
• VS Code: Use MCP: List Servers

Command Failures

The MCP server requires a .clay file for parameterless commands. Initialize if needed:

clay init

Advanced Usage

Custom Working Directory

The MCP server uses your current working directory. To work with a different project:

cd /path/to/your/project
# Then use AI assistant normally

Multiple Projects

Each project can have its own .clay file. The server uses the one in your current directory.

CI/CD Integration

The MCP server is designed for interactive use. For CI/CD, use the CLI directly:

clay generate
clay test-path ./clay/model.json "$.model.types[*]"