How Instatic's MCP Server Enables External AI Clients to Control the CMS

Instatic exposes its CMS as a capability-aware Model Context Protocol (MCP) server, allowing external AI models to discover and invoke tools via standardized JSON-RPC endpoints while reusing the platform's existing validation and security layers.

Instatic, an open-source CMS from CoreBunch, ships with a built-in Model Context Protocol (MCP) server that transforms the content management system into a programmable interface for AI agents. By implementing the MCP specification, Instatic allows external clients like Claude, GPT, and other compatible models to read pages, modify site structures, and publish content without human-in-the-loop UI interactions. This integration leverages the existing AI tool-engine to ensure consistent validation, permission checks, and real-time editor synchronization across all operations.

Architecture of the MCP Server Implementation

The MCP server implementation resides in the server/ai/mcp/ directory and integrates deeply with Instatic's existing AI infrastructure.

Server Initialization and Context

The entry point for the MCP server is located in [server/ai/mcp/server.ts](https://github.com/CoreBunch/Instatic/blob/main/server/ai/mcp/server.ts). The buildMcpServer function instantiates a new Server instance using the official @modelcontextprotocol/server SDK:

export function buildMcpServer(ctx: McpServerContext): Server {
  const server = new Server(
    { name: 'instatic', version: '1.0.0' },
    { capabilities: { tools: {} } },
  );
  // ... handler registration
  return server;
}

The McpServerContext object supplies critical runtime dependencies including the database client, authenticated user ID, connector ID (identifying the external AI client), and the list of core capabilities granted by the user (e.g., content:read, site:write). These capabilities determine which tools the AI client is permitted to access.

Capability-Based Tool Registry

Tool exposure is controlled by the mcpToolsForCapabilities function defined in [server/ai/mcp/registry.ts](https://github.com/CoreBunch/Instatic/blob/main/server/ai/mcp/registry.ts). This registry filters the complete internal toolset based on the connector's authorized capabilities, ensuring that external AI clients can only invoke operations explicitly permitted by the user. The registry may also augment tools with configuration details such as upload directories and connector-specific metadata.

Exposing CMS Tools via the Model Context Protocol

Instatic's MCP server implements the standard JSON-RPC methods defined by the Model Context Protocol specification: tools/list for discovery and tools/call for execution.

Tool Discovery (tools/list)

When an AI client requests the tool catalog via tools/list, the server iterates through the capability-filtered toolset and constructs standardized tool definitions. As implemented in [server/ai/mcp/server.ts](https://github.com/CoreBunch/Instatic/blob/main/server/ai/mcp/server.ts) (lines 28-37), each tool advertisement includes:

• A human-readable description that may include pre-conditions (such as BROWSER_WORKSPACE_REQUIREMENT indicating that a browser-based workspace must be open)
• A clean JSON Schema derived from TypeBox definitions, with symbol-keyed metadata stripped via plainInputSchema to ensure compatibility with MCP v2 validators

Tool Execution (tools/call)

The tools/call handler processes execution requests through a multi-step pipeline:

1. Tool Lookup: Validates that the requested tool name exists in the registry
2. Execution Mode Determination: Routes the request to either server (headless) or browser execution contexts
3. Capability Validation: Verifies that the connector possesses the required core capabilities for the operation

Execution Modes and Security

Instatic distinguishes between headless operations that run server-side and browser-based tools that require an active editor session.

Browser-Based Tool Execution

Tools requiring visual interaction or DOM manipulation are forwarded to the live editor via the Editor Bridge implemented in [server/ai/mcp/editorBridge.ts](https://github.com/CoreBunch/Instatic/blob/main/server/ai/mcp/editorBridge.ts). The getEditorBridgeForUser function establishes a connection to the user's open workspace.

For content-scoped tools, an additional authorization layer in [server/ai/mcp/contentAuthorization.ts](https://github.com/CoreBunch/Instatic/blob/main/server/ai/mcp/contentAuthorization.ts) performs granular permission checks via authorizeMcpContentTool before allowing the bridge call to proceed. If the required workspace is not open, the server returns an actionable error message instructing the user to open the specific editor (e.g., "Open the Site editor to use this tool").

Headless Tool Execution

Server-side tools execute directly in-process via executeAiTool from [server/ai/drivers/http/execTool.ts](https://github.com/CoreBunch/Instatic/blob/main/server/ai/drivers/http/execTool.ts). Before executing headless read operations, the system flushes pending co-editing changes using runPublishFlush to guarantee that the database reflects the latest editor state. Error handling wraps exceptions using getErrorMessage to provide AI-friendly explanations rather than raw stack traces.

Wire-Level Integration and Usage Examples

The MCP endpoint is mounted under /_instatic/mcp via the HTTP router in [server/router.ts](https://github.com/CoreBunch/Instatic/blob/main/server/router.ts), with the server instance created during application startup in [server/ai/boot.ts](https://github.com/CoreBunch/Instatic/blob/main/server/ai/boot.ts).

Listing Available Tools

External AI clients can discover available operations by calling the tools/list method:

curl -X POST https://your-instatic-instance.com/_instatic/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "params": {},
    "id": 1
  }'

The response includes tool definitions with schemas:

{
  "jsonrpc": "2.0",
  "result": {
    "tools": [
      {
        "name": "readPage",
        "description": "Read a page's JSON representation.\n\nRequires the Instatic Site editor to be open...",
        "inputSchema": {
          "type": "object",
          "properties": {
            "slug": { "type": "string" }
          },
          "required": ["slug"]
        }
      }
    ]
  },
  "id": 1
}

Invoking Headless Tools

To execute a headless read operation like readPage:

curl -X POST https://your-instatic-instance.com/_instatic/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "readPage",
      "arguments": { "slug": "about-us" }
    },
    "id": 2
  }'

Successful responses return structured content:

{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      { "type": "text", "text": "{\"ok\":true,\"title\":\"About Us\",...}" }
    ]
  },
  "id": 2
}

Handling Browser Workspace Requirements

When calling a browser-based tool like createComponent without an open editor:

{
  "jsonrpc": "2.0",
  "result": {
    "isError": true,
    "content": [
      { "type": "text", "text": "This tool runs in the Instatic Site editor. Open the Site editor..." }
    ]
  },
  "id": 3
}

Summary

• Instatic's MCP server exposes the CMS as a JSON-RPC toolset compatible with any Model Context Protocol client
• Tool access is gated by core capabilities defined in McpServerContext and enforced by the registry in server/ai/mcp/registry.ts
• Browser-based tools use the Editor Bridge (server/ai/mcp/editorBridge.ts) to interact with live workspaces, while headless tools execute via executeAiTool in the HTTP driver
• The implementation reuses existing validation and authorization layers, including content-specific checks in server/ai/mcp/contentAuthorization.ts
• The endpoint mounts at /_instatic/mcp and follows MCP specification for tool discovery and invocation

Frequently Asked Questions

What is the Model Context Protocol (MCP) in Instatic?

The Model Context Protocol is an open standard that allows AI systems to discover and interact with external tools through a standardized JSON-RPC interface. In Instatic, the MCP server implementation translates this protocol into CMS operations, enabling AI agents to read content, modify site structures, and manage media without requiring custom API integrations for each client.

How does Instatic secure MCP connections from external AI clients?

Security is enforced through capability-based access control defined in the McpServerContext. The mcpToolsForCapabilities function filters available tools based on user-granted permissions (e.g., content:read, site:write). Additionally, content-scoped operations undergo explicit authorization checks via authorizeMcpContentTool before execution, ensuring that external AI clients cannot access or modify resources beyond their granted permissions.

What happens if an AI tool requires the browser editor but it's closed?

Browser-based tools that interact with the visual editor (such as component creation or page tree manipulation) require an active workspace session. If the editor is not open, the Editor Bridge returns a structured error response with isError: true and a descriptive message instructing the user to open the specific editor (Site or Content). This prevents operations from failing silently and provides clear guidance for resuming the workflow.

Can external AI clients upload images or media through the MCP server?

Yes, the MCP server exposes tools capable of handling binary data and file uploads. Tools that support media operations receive configuration details (such as upload directories) through the registry augmentation process. The CallToolResult structure supports image attachments and binary payloads, allowing AI clients to upload images, generate screenshots via render_snapshot, and manage media assets within the capability constraints defined by the user.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}