MCP Server

The CableKnit CLI includes a built-in [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server. It gives AI coding agents — Claude Code, Cursor, Windsurf, and others — direct access to CableKnit's schemas, validation, scaffolding, and documentation without leaving the editor.

Instead of copying schemas from docs or debugging JSON by hand, you tell your agent what you want to build and it pulls the right schemas, generates files, and validates them — all through the MCP connection.

## What the MCP server provides

The server exposes 25 tools across three categories:

### Reference and lookup

| Tool | What it returns |
|---|---|
| `get_plugin_schema` | Full `plugin.json` schema with annotations |
| `get_automation_schema` | Automation template schema |
| `get_blueprint_schema` | Artifact blueprint schema |
| `get_data_source_schema` | Data source schema (data_store, connector, static) |
| `get_skill_schema` | Skill definition schema with prompt safety rules |
| `get_docs_schema` | Documentation page format (YAML frontmatter + markdown) |
| `list_platform_tools` | Available platform tools, filterable by category |
| `list_connectors` | Auth integrations (Slack, GitHub, Jira, etc.) |
| `list_industries` | Valid industry slugs |
| `list_categories` | Plugin and automation categories |
| `get_bundle_limits` | Size and count constraints (10 MB bundle, 20 skills max, etc.) |
| `get_app_guidelines` | App review criteria |
| `get_workflow_patterns` | Common automation patterns (intake routing, approval chains, escalation) |
| `get_cli_docs` | CLI documentation, optionally filtered by topic |

### Validation and debugging

| Tool | What it does |
|---|---|
| `validate_plugin_json` | Validates `plugin.json` against the schema |
| `validate_automation` | Validates an automation template |
| `validate_bundle` | Runs full bundle validation (same as `cableknit validate`) |
| `explain_error` | Explains a validation error and suggests a fix |
| `describe_automation` | Converts automation JSON to a plain-English description |
| `check_prompt_injection` | Scans skill system prompts for injection patterns |

### Generation

| Tool | What it generates |
|---|---|
| `generate_plugin_json` | Complete `plugin.json` from a description |
| `generate_automation` | Automation template with assess → complete states |
| `generate_blueprint` | Artifact blueprint with content schema |
| `generate_data_source` | Data source definition |
| `generate_skill` | Skill with a safe system prompt |
| `generate_doc_page` | Markdown doc page with YAML frontmatter |
| `scaffold_bundle` | Entire plugin bundle structure (all files + layout) |

The server also exposes resources (schemas, docs, sample bundles) and prompt templates for common workflows like building a plugin from scratch or debugging validation errors.

## Starting the MCP server

The server runs over stdio — your editor launches it automatically once configured. To set it up:

```bash
cableknit mcp install
```

This auto-detects your editor and adds the configuration. You can also specify the editor explicitly:

```bash
cableknit mcp install claude    # Claude Code
cableknit mcp install cursor    # Cursor
cableknit mcp install windsurf  # Windsurf
```

For Claude Code, this runs:

```bash
claude mcp add cableknit -- cableknit mcp
```

For Cursor and Windsurf, it adds an entry to `.cursor/mcp.json` or `.windsurf/mcp.json`.

No login is required. All MCP tools work without authentication — schemas, generation, validation, and reference data are available to any developer.

## Using the MCP server with AI agents

Once installed, your AI agent can access all CableKnit tools directly. Here are some examples of what you can ask:

### Build a plugin from scratch

> "Build a CableKnit plugin for a plumbing company that tracks service calls and generates invoices."

The agent will use `scaffold_bundle` and the generation tools to create your full bundle — `plugin.json`, automations, skills, data sources, and docs.

### Validate your work

> "Validate my plugin bundle in the current directory."

The agent calls `validate_bundle` and, if there are errors, uses `explain_error` to tell you exactly what's wrong and how to fix it.

### Look up what's available

> "What platform tools can my automations use?" or "What connectors are available?"

The agent calls `list_platform_tools` or `list_connectors` and returns the current list.

### Add to an existing plugin

> "Add an automation to my plugin that triggers when a DocuSign envelope is completed."

The agent reads your existing `plugin.json`, calls `generate_automation` with the right connector and event config, and adds the file to your bundle.

### Debug issues

> "I'm getting a validation error about my automation's trigger config. What's wrong?"

The agent calls `explain_error` with the error message and gets back a detailed explanation with the fix.

## How it works

The MCP server fetches its content — schemas, guidelines, platform tools, error explanations — from the CableKnit API. This data is cached locally (`~/.cableknit/mcp-cache/`) for 24 hours so the server stays fast and works offline.

When your agent calls a generation tool, the server uses industry-specific hints and the current schemas to produce valid output. When it validates, it runs the same checks as `cableknit validate`. The agent gets structured JSON responses it can act on directly.

## Manual setup

If `cableknit mcp install` doesn't support your editor, you can configure it manually. The server command is:

```bash
cableknit mcp
```

Point your editor's MCP configuration at this command using stdio transport. The server speaks JSON-RPC 2.0 over stdin/stdout using the MCP protocol (version 2024-11-05).

The CableKnit CLI includes a built-in Model Context Protocol (MCP) server. It gives AI coding agents — Claude Code, Cursor, Windsurf, and others — direct access to CableKnit’s schemas, validation, scaffolding, and documentation without leaving the editor.

What the MCP server provides

The server exposes 25 tools across three categories:

Reference and lookup

Tool	What it returns
`get_plugin_schema`	Full `plugin.json` schema with annotations
`get_automation_schema`	Automation template schema
`get_blueprint_schema`	Artifact blueprint schema
`get_data_source_schema`	Data source schema (data_store, connector, static)
`get_skill_schema`	Skill definition schema with prompt safety rules
`get_docs_schema`	Documentation page format (YAML frontmatter + markdown)
`list_platform_tools`	Available platform tools, filterable by category
`list_connectors`	Auth integrations (Slack, GitHub, Jira, etc.)
`list_industries`	Valid industry slugs
`list_categories`	Plugin and automation categories
`get_bundle_limits`	Size and count constraints (10 MB bundle, 20 skills max, etc.)
`get_app_guidelines`	App review criteria
`get_workflow_patterns`	Common automation patterns (intake routing, approval chains, escalation)
`get_cli_docs`	CLI documentation, optionally filtered by topic

Validation and debugging

Tool	What it does
`validate_plugin_json`	Validates `plugin.json` against the schema
`validate_automation`	Validates an automation template
`validate_bundle`	Runs full bundle validation (same as `cableknit validate`)
`explain_error`	Explains a validation error and suggests a fix
`describe_automation`	Converts automation JSON to a plain-English description
`check_prompt_injection`	Scans skill system prompts for injection patterns

Generation

Tool	What it generates
`generate_plugin_json`	Complete `plugin.json` from a description
`generate_automation`	Automation template with assess → complete states
`generate_blueprint`	Artifact blueprint with content schema
`generate_data_source`	Data source definition
`generate_skill`	Skill with a safe system prompt
`generate_doc_page`	Markdown doc page with YAML frontmatter
`scaffold_bundle`	Entire plugin bundle structure (all files + layout)

The server also exposes resources (schemas, docs, sample bundles) and prompt templates for common workflows like building a plugin from scratch or debugging validation errors.

Starting the MCP server

The server runs over stdio — your editor launches it automatically once configured. To set it up:

cableknit mcp install

This auto-detects your editor and adds the configuration. You can also specify the editor explicitly:

cableknit mcp install claude    # Claude Code
cableknit mcp install cursor    # Cursor
cableknit mcp install windsurf  # Windsurf

For Claude Code, this runs:

claude mcp add cableknit -- cableknit mcp

For Cursor and Windsurf, it adds an entry to .cursor/mcp.json or .windsurf/mcp.json.

No login is required. All MCP tools work without authentication — schemas, generation, validation, and reference data are available to any developer.

Using the MCP server with AI agents

Once installed, your AI agent can access all CableKnit tools directly. Here are some examples of what you can ask:

Build a plugin from scratch

“Build a CableKnit plugin for a plumbing company that tracks service calls and generates invoices.”

The agent will use scaffold_bundle and the generation tools to create your full bundle — plugin.json, automations, skills, data sources, and docs.

Validate your work

“Validate my plugin bundle in the current directory.”

The agent calls validate_bundle and, if there are errors, uses explain_error to tell you exactly what’s wrong and how to fix it.

Look up what’s available

“What platform tools can my automations use?” or “What connectors are available?”

The agent calls list_platform_tools or list_connectors and returns the current list.

Add to an existing plugin

“Add an automation to my plugin that triggers when a DocuSign envelope is completed.”

The agent reads your existing plugin.json, calls generate_automation with the right connector and event config, and adds the file to your bundle.

Debug issues

“I’m getting a validation error about my automation’s trigger config. What’s wrong?”

The agent calls explain_error with the error message and gets back a detailed explanation with the fix.

How it works

The MCP server fetches its content — schemas, guidelines, platform tools, error explanations — from the CableKnit API. This data is cached locally (~/.cableknit/mcp-cache/) for 24 hours so the server stays fast and works offline.

When your agent calls a generation tool, the server uses industry-specific hints and the current schemas to produce valid output. When it validates, it runs the same checks as cableknit validate. The agent gets structured JSON responses it can act on directly.

Manual setup

If cableknit mcp install doesn’t support your editor, you can configure it manually. The server command is:

cableknit mcp

Point your editor’s MCP configuration at this command using stdio transport. The server speaks JSON-RPC 2.0 over stdin/stdout using the MCP protocol (version 2024-11-05).