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