---
search: true
---

# MCP Server

The Modyo MCP (Model Context Protocol) Server is a tool based on two fundamental principles: AI integration and platform automation, implemented through natural language commands that interact directly with Modyo platform APIs.

## Benefits of the MCP Server

- **67 Tools**: Smart "manage" tools that combine multiple operations with 70-90% token reduction.
- **Secure Authentication**: Uses token-based authentication for secure access.
- **Universal Client Support**: Works with Claude Code, VS Code, Cursor, and other MCP-compatible clients.

## Modules

The server includes four modules in a single package:

| Module | Description |
|--------|-------------|
| **Content** | Headless CMS - spaces, entries, types, assets, categories |
| **Channels** | Digital Experience - sites, pages, widgets, templates, navigation |
| **Customers** | Identity Management - realms, users, forms, submissions |
| **Core** | Platform Administration - team users, groups, roles, settings |

## Installation

### Option 1: npx (Recommended)

The simplest way to use the MCP server:

```bash
npx @modyo/mcp
```

### Option 2: Global Installation

```bash
npm install -g @modyo/mcp
modyo-mcp
```

### Option 3: From Source

```bash
git clone https://github.com/modyo/modyo-mcp-server
cd modyo-mcp-server
npm install
npm run build
npm start
```

## Environment Configuration

### Required Environment Variables

| Variable | Example | Description |
|----------|---------|-------------|
| `MODYO_URL` | `https://my-company.modyo.cloud` | Your Modyo platform URL |
| `MODYO_TOKEN` | `eyJ...` | API token from Modyo Admin → Settings → API Access |

### Optional Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `MODYO_PLATFORM_NAME` | `default` | Name to identify the platform |
| `DEBUG` | `false` | Enable debug logging |

### Previous Actions

- **Get a Modyo access token**: To get the token, you need to have a user or [create one](/en/platform/core/roles.html#create-user) with at least the [role](/en/platform/core/roles.html#roles) of `developer` on the sites, spaces, or realms where you'll interact. Once the user is created, you can [configure an access token](/en/platform/core/api.html#authentication) for them.

- **Identify your platform URL**: Get the base URL of your Modyo organization (e.g., `https://my-company.modyo.com`).

## Client Configuration

### Claude Code

```bash
claude mcp add modyo -- npx @modyo/mcp \
  --env MODYO_URL=https://my-company.modyo.cloud \
  --env MODYO_TOKEN=your_api_token
```

Or if you installed from source:

```bash
claude mcp add modyo -- node /path/to/modyo-mcp-server/build/index.js \
  --env MODYO_URL=https://my-company.modyo.cloud \
  --env MODYO_TOKEN=your_api_token
```

### Claude Desktop

1. **Locate the configuration file**:
   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
   - **Linux**: `~/.config/Claude/claude_desktop_config.json`

2. **Add the configuration**:

```json
{
  "mcpServers": {
    "modyo": {
      "command": "npx",
      "args": ["@modyo/mcp"],
      "env": {
        "MODYO_URL": "https://my-company.modyo.cloud",
        "MODYO_TOKEN": "your_api_token"
      }
    }
  }
}
```

3. **Restart Claude Desktop**

### VS Code / Cursor

Add to your `.vscode/mcp.json` file:

```json
{
  "servers": {
    "modyo": {
      "command": "npx",
      "args": ["@modyo/mcp"],
      "env": {
        "MODYO_URL": "https://my-company.modyo.cloud",
        "MODYO_TOKEN": "your_api_token"
      }
    }
  }
}
```

### Gemini CLI

Add to your `~/.gemini/settings.json` file:

```json
{
  "mcpServers": {
    "modyo": {
      "command": "npx",
      "args": ["@modyo/mcp"],
      "env": {
        "MODYO_URL": "https://my-company.modyo.cloud",
        "MODYO_TOKEN": "your_api_token"
      }
    }
  }
}
```

## Tools Reference

The following tools are available. These are smart "manage" tools that combine multiple operations into efficient workflows with 70-90% token reduction.

:::tip Best Practice
Most LLM clients allow you to enable or disable individual tools. Keep only the tools you need enabled to maintain a clean context and help the AI focus on what matters.
:::

### Content Module

| Tool | Description |
|------|-------------|
| `content-spaces-manage` | Complete space lifecycle |
| `content-spaces-copy` | Clone spaces |
| `content-types-manage` | Content type schema management |
| `content-types-upsert` | Idempotent type management by UID |
| `content-types-copy` | Copy content types |
| `content-entries-manage` | Entry lifecycle including publish/unpublish |
| `content-entries-upsert` | Idempotent entry management by slug |
| `content-entries-bulk` | Bulk operations with preview |
| `content-assets-manage` | Asset management |
| `content-assets-bulk` | Bulk asset upload |
| `content-categories-manage` | Category hierarchy management |

### Channels Module

| Tool | Description |
|------|-------------|
| `channels-sites-manage` | Complete site lifecycle |
| `channels-sites-overview` | Get complete site overview |
| `channels-pages-manage` | Page management |
| `channels-pages-widget` | Widget page authoring (full widget layout, replace-all) |
| `channels-pages-widget-instance` | Atomic CRUD of a single widget instance |
| `channels-pages-widget-variables` | Per-slug variable management for a widget instance |
| `channels-pages-content` | Content pages with Liquid templates |
| `channels-pages-copy` | Copy pages |
| `channels-widgets-manage` | Complete widget lifecycle |
| `channels-widgets-upsert` | Idempotent widget management |
| `channels-widgets-copy` | Copy widgets |
| `channels-templates-manage` | Complete template lifecycle |
| `channels-templates-upsert` | Idempotent template management |
| `channels-templates-copy` | Copy templates |
| `channels-menus-manage` | Navigation menu management |
| `channels-menu-items-manage` | Menu item management |
| `channels-menus-copy` | Copy menus |
| `channels-variables-manage` | Global variables |
| `channels-publish` | Smart publishing workflow |

### Customers Module

| Tool | Description |
|------|-------------|
| `customers-realms-manage` | Complete realm lifecycle |
| `customers-users-manage` | User management by email |
| `customers-users-bulk` | Bulk user operations |
| `customers-forms-manage` | Complete form lifecycle |
| `customers-forms-copy` | Copy forms |
| `customers-datasets-manage` | Data set management |
| `customers-datasets-copy` | Copy data sets |
| `customers-originations-manage` | Origination lifecycle |
| `customers-submissions-manage` | Submission management |
| `customers-submissions-bulk` | Bulk submission operations |

### Core Module

| Tool | Description |
|------|-------------|
| `core-users-manage` | Team user lifecycle |
| `core-users-upsert` | Idempotent operations by email |
| `core-users-bulk` | Bulk activate/deactivate |
| `core-groups-manage` | Group lifecycle |
| `core-groups-upsert` | Idempotent operations by name |
| `core-team-manage` | Assign users/groups to resources |
| `core-roles-list` | List available roles |
| `core-settings-manage` | Platform settings |

## Usage Examples

Once configured, you can interact with Modyo using natural language:

```
"List all spaces in my platform"

"Create a content type called 'Products' with fields: name (text), price (number)"

"Create an entry in the blog space with title 'Hello World'"

"Show all published widgets for site ID 5"

"Publish all pending pages and widgets for site 4605"

"Assign user john@example.com to the marketing site with editor role"
```

## Troubleshooting

### "Platform not configured" errors

- Verify that `MODYO_URL` and `MODYO_TOKEN` environment variables are set
- Ensure the token has the correct permissions

### Tools not visible

1. Verify the server is running
2. Restart your MCP client
3. Check MCP client logs for errors

### Authentication errors

- Verify API tokens have correct permissions
- Ensure API endpoints are correct

:::warning Attention
The token owner user must have appropriate permissions for the operations you want to perform.
:::