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

> Learn how Instatic's MCP server enables external AI clients to control the CMS by exposing it as a capability-aware MCP server with standardized JSON-RPC endpoints.

- Repository: [CoreBunch/Instatic](https://github.com/CoreBunch/Instatic)
- Tags: internals
- Published: 2026-08-01

---

**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)](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:

```typescript
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)](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)](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)](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)](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)](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)](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)](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:

```bash
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:

```json
{
  "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`:

```bash
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:

```json
{
  "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:

```json
{
  "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`](https://github.com/CoreBunch/Instatic/blob/main/server/ai/mcp/registry.ts)
- **Browser-based tools** use the Editor Bridge ([`server/ai/mcp/editorBridge.ts`](https://github.com/CoreBunch/Instatic/blob/main/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`](https://github.com/CoreBunch/Instatic/blob/main/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.