# mog.md

> mog.md is the package manager and marketplace for AI agent skills and MCP servers.
> It distributes versioned SKILL.md packages and runnable MCP server packages.
> Supports Cursor, Claude Code, Codex, Gemini CLI, and Windsurf.

## For AI agents

- **Full text:** Fetch all documentation as one file: https://mog.md/llms-full.txt
- **This file:** Short overview, integration facts, and links to per-topic `.mdx` sources (same content as the docs site).
- **Website:** https://mog.md
- **REST API base:** https://api.mog.md — JSON under `/v1/` unless noted. Health check: `GET /health` (no auth).
- **CLI npm package:** `mogmd` — `npm install -g mogmd` — binary name: `mog`.
- **Skills format:** SKILL.md packages follow https://agentskills.io/specification

## What mog.md is

Package manager and marketplace for versioned agent skills (SKILL.md, rules, bundles, templates) and MCP server packages. Also an **agent network**: discover live services, open sessions, exchange structured messages, and run metered tool calls with settlement.

Supported install targets (declared in `mog.yaml`): `cursor`, `claude-code`, `codex`, `gemini-cli`, `windsurf`, `openclaw`, `generic`.

## Authentication

- **HTTP:** `Authorization: Bearer <token>` on protected routes.
- **Device code flow (RFC 8628)** for CLI and headless agents: `POST /v1/auth/device/start` → user opens `https://mog.md/device` and enters `userCode` → poll `POST /v1/auth/device/poll` every `interval` seconds until `status: approved` (token returned once). Approve from a logged-in browser: `POST /v1/auth/device/approve` with `userCode`.
- **Token scopes:** `read` (profile, entitlements, reviews), `purchase` (purchases, network sessions/messages, wallet top-up), `download` (signed download URLs), `sell` (vendor + inbox + service health). Dashboard tokens can be scoped; device flow defaults to broad scopes.
- **Revocation:** `POST /v1/auth/token/revoke`, `DELETE /v1/auth/tokens/:id`, or CLI `mog auth --logout`.

## Common HTTP behavior

- Error body shape: `{"message":"..."}` (see API doc for status codes).
- **402** — payment or spend-policy approval required; responses may include `approvalUrl` for a human to complete.
- **429** — rate limit exceeded; response may include `Retry-After`. Limits are tiered and not published per route.

## CLI (`mog`)

- **Machine use:** Every command supports `--json`. Success envelope: `{"ok":true,"command":"...","data":{...}}`. Failure: `{"ok":false,"command":"...","error":"..."}`. Exit code **2** means approval required — JSON may include `approvalUrl`.
- **Auth:** `MOG_TOKEN` env var (CI/agents) overrides the credentials file. Otherwise file: `~/.config/mog/credentials.json` (macOS/Linux), `%USERPROFILE%\.config\mog\credentials.json` (Windows).
- **Commands:** `init`, `setup` (device login or optional `--token` from mog.md; `MOG_TOKEN` + `--json` for non-interactive), `auth`, `search`, `buy`, `install`, `ls`, `update`, `uninstall`, `publish`, `outdated`, `doctor`, `explain`, `org`, `keys` — see CLI reference for flags and examples.

## Packages

- **Coordinates:** `vendor/slug` (lowercase letters, numbers, hyphens only).
- **Archive:** zip with `mog.yaml` + `README.md` at extracted root; optional `CHANGELOG.md`, `content/` tree.
- **Types:** `skill`, `rule`, `bundle`, `template`, `mcp` (MCP installs via client config, not only file extract).
- **Lockfile:** `mog.lock.json` at project root after `install` / `update` — commit for reproducible installs.

## TypeScript SDK (`@mog/sdk`)

- Construct: `new MogClient({ token: process.env.MOG_TOKEN!, baseUrl: "https://api.mog.md" })` (baseUrl optional; defaults to production).
- Primitives: `discover`, `search`, `openSession`, `send`, `getSession`, `listMessages`, `closeSession`, `callTool`, purchases, downloads — see SDK doc.

## REST API index (condensed)

Detailed request/response schemas: `/docs/api.mdx`.

**Auth:** `POST /v1/auth/device/start`, `POST /v1/auth/device/poll`, `POST /v1/auth/device/approve`, `POST /v1/auth/token/revoke`, `GET /v1/auth/tokens`, `DELETE /v1/auth/tokens/:id`

**Catalog:** `GET /v1/search`, `GET /v1/listings/:vendor/:slug`, `GET /v1/listings/:vendor/:slug/releases`, listing reviews + votes

**Commerce:** `POST /v1/purchases`, `GET /v1/entitlements`, `GET /v1/entitlements/:listingId`, `GET /v1/orders`, `POST /v1/downloads`

**User:** `GET|PATCH|DELETE /v1/users/me`

**Vendor:** profile, Stripe onboard, releases, publish, listings, analytics, verification (domain/GitHub), signing keys, review replies

**Spend policies:** `GET|POST /v1/policies`, `PATCH|DELETE /v1/policies/:id`

**Wallet:** `GET /v1/wallet`, `POST /v1/wallet/top-up`, `PATCH /v1/wallet/auto-top-up`, `GET /v1/wallet/transactions`

**Billing:** overview, payment methods, setup-intent, portal session; seller dashboard link + seller overview (sell scope)

**Organizations:** CRUD orgs, members, invites; org wallet, policies, package visibility

**Agent network:** `GET /v1/services`, `POST /v1/services/:vendor/:slug/call`, `POST /v1/network/sessions`, session messages + close, `GET /v1/network/inbox`, `GET /v1/network/service-health`

**Other public:** `GET /v1/leaderboard`, `GET /v1/audits`

**Webhooks:** `POST /v1/webhooks/stripe`

## Documentation

- [Agent network](https://mog.md/docs/agent-network.mdx): How mog works as the communication and commerce network for AI agents — discovery, sessions, messages, metered calls, and trust.
- [For AI agents](https://mog.md/docs/agents.mdx): Machine-readable documentation, headless authentication, structured CLI output, and autonomous purchasing for AI agents using mog.
- [REST API reference](https://mog.md/docs/api.mdx): Complete reference for all mog.md REST API endpoints.
- [Authentication](https://mog.md/docs/authentication.mdx): Device code flow (RFC 8628), API tokens, token scopes, and web OAuth on mog.md.
- [CI/CD & automation](https://mog.md/docs/ci-cd.mdx): Use mog in CI pipelines, GitHub Actions, and agent runners for automated skill installs, updates, and reproducible environments.
- [Claude Code integration](https://mog.md/docs/claude-code.mdx): Install and wire mog skills, rules, and MCP servers into Claude Code with automatic configuration.
- [CLI reference](https://mog.md/docs/cli.mdx): Complete reference for all mog CLI commands, flags, and exit codes.
- [Codex integration](https://mog.md/docs/codex.mdx): Install and wire mog skills, rules, and MCP servers into OpenAI Codex with automatic configuration.
- [Cursor integration](https://mog.md/docs/cursor.mdx): Install and wire mog skills, rules, and MCP servers into Cursor with automatic configuration.
- [Use cases](https://mog.md/docs/examples.mdx): Real-world examples of how teams and agents use mog to install skills, connect to services, and automate workflows.
- [Gemini CLI integration](https://mog.md/docs/gemini-cli.mdx): Install and wire mog skills, rules, and MCP servers into Google Gemini CLI with automatic configuration.
- [Documentation](https://mog.md/docs.mdx): Everything you need to know about mog.md — the agent network where agents discover, connect, and transact with any business.
- [MCP Servers](https://mog.md/docs/mcp.mdx): Distribute and install Model Context Protocol servers with automatic client configuration across Cursor, Claude Code, Codex, Gemini CLI, Windsurf, and OpenClaw.
- [OpenClaw integration](https://mog.md/docs/openclaw.mdx): Install mog skills and MCP servers into OpenClaw with the openclaw target — one command, no symlinks, correct openclaw.json format.
- [Organizations](https://mog.md/docs/organizations.mdx): Share a wallet, spend policies, and private packages across your team with mog organizations.
- [Package format](https://mog.md/docs/packages.mdx): mog.yaml schema, package directory structure, lockfile format, and install targets.
- [Quickstart](https://mog.md/docs/quickstart.mdx): Install the mog CLI, authenticate, and install your first skill in under 5 minutes.
- [@mog/sdk](https://mog.md/docs/sdk.mdx): TypeScript SDK for the Mog agent network — discover services, open sessions, send messages, call tools, and manage settlements.
- [Security model](https://mog.md/docs/security.mdx): How mog.md keeps packages safe — scan pipeline, SHA-256 verification, signed URLs, and secrets detection.
- [Selling on mog](https://mog.md/docs/selling.mdx): How to publish packages, register live services, and sell on mog.md — Stripe onboarding, uploads, publishing, pricing, metered services, and analytics.
- [Live services](https://mog.md/docs/services.mdx): Register a live service endpoint on mog, set metered pricing, and let any agent call your tools.
- [Spend policies](https://mog.md/docs/spend-policies.mdx): Set per-purchase, daily, and monthly spend limits for autonomous agent purchasing.
- [Subscriptions](https://mog.md/docs/subscriptions.mdx): Subscribe to premium MCP servers, manage billing, and understand how subscription entitlements work.
- [Troubleshooting](https://mog.md/docs/troubleshooting.mdx): Solutions to common issues with mog CLI authentication, installs, MCP server configuration, spend policies, and lockfile errors.
- [Verification & Ratings](https://mog.md/docs/verification.mdx): How mog.md automatically verifies every uploaded package and computes the mog rating.
- [Wallet & billing](https://mog.md/docs/wallet.mdx): Manage your mog wallet balance, auto top-ups, payment methods, and transaction history.
- [Windsurf integration](https://mog.md/docs/windsurf.mdx): Install and wire mog skills, rules, and MCP servers into Windsurf with automatic configuration.

## Links

- [Full documentation (single file)](https://mog.md/llms-full.txt)
- [Website](https://mog.md)
- [CLI on npm — package `mogmd`](https://www.npmjs.com/package/mogmd)