# Modyo MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for managing [Modyo](https://www.modyo.com) platform instances. Connect your AI assistants directly to Modyo's APIs for content management, site building, and platform administration.

## Table of Contents

- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
  - [Claude Desktop](#claude-desktop)
  - [Claude Code](#claude-code)
  - [GitHub Copilot in VS Code](#github-copilot-in-vs-code)
  - [GitHub Copilot CLI](#github-copilot-cli)
  - [Gemini CLI](#gemini-cli)
  - [Cursor](#cursor)
  - [Other MCP clients](#other-mcp-clients)
- [Environment Variables](#environment-variables)
- [Available Modules](#available-modules)
- [Usage Examples](#usage-examples)
- [Development](#development)
- [Troubleshooting](#troubleshooting)
- [Resources](#resources)
- [License](#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`

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

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

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

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

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

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

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

```bash
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](./CLAUDE.md) for development guidelines and architecture details.

---

## Troubleshooting

**"Platform not configured" error:**

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

```bash
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](https://github.com/github/copilot-cli/issues/1050), 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](https://docs.modyo.com)
- [Model Context Protocol](https://modelcontextprotocol.io)

---

## License

Modyo Agreement © [Modyo](https://www.modyo.com)