@modyo/mcp

Modyo MCP Server

A Model Context Protocol (MCP) server for managing Modyo platform instances. Connect your AI assistants directly to Modyo's APIs for content management, site building, and platform administration.

Table of Contents

• Features
• Requirements
• Installation
  • Claude Desktop
  • Claude Code
  • GitHub Copilot in VS Code
  • GitHub Copilot CLI
  • Gemini CLI
  • Cursor
  • Other MCP clients
• Environment Variables
• Available Modules
• Usage Examples
• Development
• Troubleshooting
• Resources
• License

Features

• Simple Setup — Configure with two environment variables
• Comprehensive Tools — API coverage across 4 modules
• TypeScript — Fully typed with Zod schema validation
• Stdio Transport — Works with Claude Code, VS Code, Cursor, and other MCP clients

Requirements

• Node.js 22+
• A Modyo platform instance
• A Modyo admin API token

Installation

Claude Desktop

Add to your claude_desktop_config.json:

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

{
  "mcpServers": {
    "modyo": {
      "command": "npx",
      "args": ["-y", "@modyo/mcp"],
      "env": {
        "MODYO_URL": "https://your-org.modyo.com",
        "MODYO_TOKEN": "your-admin-token"
      }
    }
  }
}

Restart Claude Desktop after saving.

Claude Code

claude mcp add modyo \
  --scope project \
  --env MODYO_URL=https://your-org.modyo.com \
  --env MODYO_TOKEN=your-token \
  -- npx -y @modyo/mcp

Use --scope user instead of --scope project to apply the configuration globally across all projects.

Verify the server was registered:

claude mcp list

GitHub Copilot in VS Code

Requires Copilot with Agent Mode enabled.

Per project (recommended — commit with your repo):

Create .vscode/mcp.json in your project root:

{
  "servers": {
    "modyo": {
      "command": "npx",
      "args": ["-y", "@modyo/mcp"],
      "env": {
        "MODYO_URL": "https://your-org.modyo.com",
        "MODYO_TOKEN": "your-token"
      }
    }
  }
}

A Start button will appear at the top of the file. Click it to start the server and let Copilot discover the available tools.

Global (applies to all projects):

Open Command Palette → Chat: Open User MCP Configuration and add the same configuration.

Note for organizations: If your account is Copilot Business or Enterprise, an administrator must enable the "MCP servers in Copilot" policy in your organization settings.

GitHub Copilot CLI

Option A — Interactive (recommended):

Inside a Copilot CLI session, run:

/mcp add

Follow the wizard: select Local or STDIO, enter npx -y @modyo/mcp as the command, and add the environment variables.

Option B — Edit config file directly:

Edit ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "modyo": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "@modyo/mcp"],
      "env": {
        "MODYO_URL": "https://your-org.modyo.com",
        "MODYO_TOKEN": "your-token"
      },
      "tools": ["*"]
    }
  }
}

Verify the server is registered:

/mcp show

Note: Copilot CLI's auto-compaction can corrupt the message history during large tool call responses, producing a CAPIError: 400 error. See Troubleshooting for workarounds.

Gemini CLI

Edit ~/.gemini/settings.json for a global setup, or .gemini/settings.json in your project for a per-project setup:

{
  "mcpServers": {
    "modyo": {
      "command": "npx",
      "args": ["-y", "@modyo/mcp"],
      "env": {
        "MODYO_URL": "https://your-org.modyo.com",
        "MODYO_TOKEN": "your-token"
      }
    }
  }
}

Important: Gemini CLI automatically redacts environment variables matching sensitive patterns like *TOKEN*. Always declare MODYO_TOKEN explicitly in the env block as shown above — do not rely on shell environment variables.

Verify inside Gemini CLI:

/mcp

Cursor

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "modyo": {
      "command": "npx",
      "args": ["-y", "@modyo/mcp"],
      "env": {
        "MODYO_URL": "https://your-org.modyo.com",
        "MODYO_TOKEN": "your-token"
      }
    }
  }
}

Other MCP clients

Any client that supports the MCP stdio transport:

command: npx
args: ["-y", "@modyo/mcp"]
env:
  MODYO_URL: https://your-org.modyo.com
  MODYO_TOKEN: your-token

Environment Variables

Variable	Required	Description
MODYO_URL	Yes	Platform URL (e.g., https://company.modyo.cloud)
MODYO_TOKEN	Yes	API token — Modyo Admin → Settings → API Access
MODYO_PLATFORM_NAME	No	Display name for the platform (default: "default")
DEBUG	No	Enable debug logging

Without MODYO_URL and MODYO_TOKEN, the server starts in public mode and only exposes tools that don't require authentication. Useful for exploring available capabilities.

Available Modules

Module	Description
Content	Spaces, types, entries, assets, categories
Channels	Sites, pages, widgets, templates, navigation
Customers	Realms, users, forms, submissions
Core	Admin users, groups, roles

Usage Examples

"List all spaces in my platform"
"Create a content type called 'Products' with name and price fields"
"Show all widgets for site ID 5"
"Publish all pending changes for site 123"
"Create a new page at /about with the Base layout"

Development

git clone https://github.com/modyo/modyo-mcp-server
cd modyo-mcp-server
npm install
npm run build
npm test
npm run lint:fix

See CLAUDE.MD for development guidelines and architecture details.

Troubleshooting

"Platform not configured" error:

# Verify environment variables are set
echo $MODYO_URL
echo $MODYO_TOKEN

# Test the API token directly
curl -H "Authorization: Bearer $MODYO_TOKEN" "$MODYO_URL/api/admin/account"

Build errors:

npm run clean && npm run build

Gemini CLI — authentication fails silently:

Gemini CLI filters environment variables matching *TOKEN* before passing them to MCP servers. Make sure MODYO_TOKEN is declared explicitly in the env block of your settings.json, not just exported in your shell.

GitHub Copilot CLI — CAPIError: 400 after tool calls:

Copilot CLI's auto-compaction can drop the tool_calls message while retaining the tool response, corrupting the conversation history. This is a known CLI bug, not a server issue.

Workarounds:

• Start a fresh session: rm -rf ~/.copilot/session-state && copilot --allow-all-tools
• Keep tool call responses small — ask for specific fields instead of full objects (e.g. "list sites, return only id, name and host")

Resources

• Modyo Documentation
• Model Context Protocol

License

Modyo Agreement © Modyo