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 mcpServers entry to the correct config file for your AI tool
4. Updates mog.lock.json
5. Prints a reminder to restart your IDE

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
generic	.mcp.json	project

Target is auto-detected from marker directories (.cursor/, .claude/, .windsurf/, .gemini/, .codex/) 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..."
    }
  }
}