MCP Servers

mog.md supports distributing MCP (Model Context Protocol) servers as a first-class package type. When you install an MCP server package, the CLI automatically writes the correct configuration to your AI tool — no manual JSON editing required.

What is an MCP server?

MCP servers are programs that extend AI agents with external tools, resources, and data sources. They communicate with AI tools via JSON-RPC 2.0 over stdio or HTTP. Common examples: GitHub integration, database access, Slack, Notion, custom APIs.

Install an MCP server

# Auto-detects your AI tool from the project directory
mog install acme/github-mcp-server --auto-buy
 
# Specify target explicitly
mog install acme/github-mcp-server --target cursor
 
# Pass required env vars non-interactively (for CI / headless)
mog install acme/github-mcp-server --env GITHUB_TOKEN=ghp_xxx --auto-buy

On install the CLI:

1. Downloads and SHA-256 verifies the package archive
2. Prompts for any required environment variables (or reads them from --env)
3. Writes the server entry to the correct config file for your AI tool (mcpServers for most clients; OpenClaw uses nested mcp.servers in ~/.openclaw/openclaw.json)
4. Updates mog.lock.json
5. Prints a reminder to restart your IDE (or restart the OpenClaw gateway for openclaw target)

Supported clients and config files

Target	Config file written	Scope
cursor	.cursor/mcp.json	project
claude-code	.mcp.json	project
codex	.codex/config.toml	project
gemini-cli	.gemini/settings.json	project
windsurf	~/.codeium/windsurf/mcp_config.json	global
openclaw	~/.openclaw/openclaw.json (mcp.servers)	global
generic	.mcp.json	project

Target is auto-detected from marker directories (.cursor/, .claude/, .windsurf/, .gemini/, .codex/, .openclaw/) in the current working directory. Use --target to override.

Uninstall an MCP server

mog uninstall acme/github-mcp-server

Removes the mcpServers entry from the client config and deletes the lockfile entry. Restart your IDE after uninstalling.

Publishing an MCP server

Package structure

your-mcp-server/
  mog.yaml         # Required
  README.md        # Required
  CHANGELOG.md     # Optional
  src/
    index.ts       # Your MCP server source
  package.json
  tsconfig.json

mog.yaml for MCP packages

The type must be mcp and a mcp block is required:

name: acme/github-mcp-server
version: 1.0.0
type: mcp
description: MCP server for GitHub — browse repos, create issues, manage PRs.
targets:
  - cursor
  - claude-code
  - codex
  - gemini-cli
  - windsurf
  - generic
 
mcp:
  transport: stdio           # stdio (local subprocess) or http (remote URL)
  command: npx               # executable (npx, node, python, python3, uvx, docker)
  args:
    - "-y"
    - "@acme/github-mcp-server@{version}"   # {version} is replaced at install time
  env:
    - name: GITHUB_TOKEN
      description: "GitHub personal access token with repo scope"
      required: true
      secret: true
    - name: GITHUB_ORG
      description: "Default GitHub organization (optional)"
      required: false
      secret: false
 
license: MIT
readme: README.md

mcp field reference

Field	Type	Required	Description
transport	stdio | http	Yes	How the AI tool connects to the server
command	string	For stdio	Executable to run (npx, node, python, python3, uvx, docker)
args	string[]	No	Arguments passed to command. Use {version} as a placeholder.
env	EnvVar[]	No	Environment variables the server requires
url	string	For http	Server URL (http transport only)
headers	object	No	HTTP headers (http transport only, e.g. Authorization)

EnvVar fields

Field	Type	Default	Description
name	string	—	Env var name (uppercase, e.g. GITHUB_TOKEN)
description	string	—	Shown to users at install time
required	boolean	true	If true, install fails if value not provided
secret	boolean	false	Marks as sensitive (shown as **** in previews)

HTTP transport example

For remotely-hosted MCP servers:

mcp:
  transport: http
  url: "https://mcp.acme.dev/github"
  headers:
    Authorization: "Bearer {env:ACME_API_KEY}"
  env:
    - name: ACME_API_KEY
      description: "API key from acme.dev dashboard"
      required: true
      secret: true

Allowed commands

For security, only these executables are accepted in mcp.command:

npx, node, python, python3, uvx, uv, docker, bunx, bun

Packages with other commands will fail the scan pipeline.

Allowed file types

MCP packages may include source code files in addition to Markdown content:

.ts, .tsx, .js, .mjs, .cjs, .py, .pyi, .toml, .lock, .sh, .env.example, .gitignore, .npmignore, .md, .yaml, .yml, .txt, .json, .png, .jpg, .svg

Publish

mog publish --dir ./my-mcp-server --price 4.99

The scan pipeline validates the mcp block, checks that command is in the approved list, and scans for shell injection patterns in args.

What the installed config looks like

After mog install acme/github-mcp-server --target cursor, the CLI writes to .cursor/mcp.json:

{
  "mcpServers": {
    "acme-github-mcp-server": {
      "command": "npx",
      "args": ["-y", "@acme/github-mcp-server@1.0.0"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token"
      }
    }
  }
}

For Codex (.codex/config.toml):

[mcp_servers.acme-github-mcp-server]
command = "npx"
args = ["-y", "@acme/github-mcp-server@1.0.0"]
 
[mcp_servers.acme-github-mcp-server.env]
GITHUB_TOKEN = "ghp_your_token"

Restart your IDE after any config change for the MCP server to be discovered.

Lockfile tracking

MCP installs are recorded in mog.lock.json with installType: "mcp-config":

{
  "packages": {
    "acme/github-mcp-server": {
      "version": "1.0.0",
      "target": "cursor",
      "installType": "mcp-config",
      "mcpConfigPaths": ["/my-project/.cursor/mcp.json"],
      "archiveSha256": "a3f8c2d1..."
    }
  }
}

Premium MCP servers

Some MCP servers require a subscription for access. These are hosted, managed services — zero installation on your machine, and the vendor handles uptime and authentication.

Subscribe

# Subscribe with monthly billing (default)
mog subscribe acme/premium-mcp
 
# Subscribe with annual billing (save up to 20%)
mog subscribe acme/premium-mcp --interval annual
 
# Subscribe on behalf of an org
mog subscribe acme/premium-mcp --org my-company

After subscribing, the CLI prints an mog install command to write the MCP config for your AI tool.

Cancel

# Cancel at end of current billing period (you keep access until then)
mog unsubscribe acme/premium-mcp
 
# Cancel immediately (access revoked now)
mog unsubscribe acme/premium-mcp --immediate

What happens when a subscription expires?

• stdio MCPs: The existing mcpServers config entry stays in place after expiry — your AI tool will still try to launch the process. The next mog install or mog subscribe will fail until you reactivate. This is intentional graceful degradation per the MCP stdio spec.
• HTTP MCPs: Access may be revoked at the server level, depending on the vendor's implementation.

Compliance

mog follows the MCP Protocol specification for both stdio and Streamable HTTP transports. Premium HTTP MCP servers use OAuth 2.1 (with PKCE) for authorization per the MCP Authorization spec.

See Subscriptions for the full billing guide.