Skip to content

docs: address extend-section review findings #26

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
charlesrhoward merged 1 commit into from
Apr 24, 2026
+42 −18
Merged

docs: address extend-section review findings #26

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 9 additions & 3 deletions content/docs/cli/skills/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,14 +38,20 @@ The canonical skill files live in the docs repo at `skills/<name>/SKILL.md` and

## Install

The skill files are hosted in [`webrenew/mogplex-docs`](https://github.com/webrenew/mogplex-docs) under `skills/`. Fetch them first, then copy into your agent host.

### Claude Code

```bash
# Fetch just the skills/ tree (no full clone needed)
npx -y degit webrenew/mogplex-docs/skills mogplex-skills
Copy link
Copy Markdown

@mogplex mogplex Bot Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Warning: Install instructions are inconsistent between extend/skills.mdx and cli/skills/index.mdx

The two pages address the same install task but diverge in a way that will confuse readers who visit both:

  • extend/skills.mdx (Option B) downloads to mogplex-skills/, then the subsequent copy block uses cp -R skills/* ~/.claude/skills/ — which requires the user to be inside a directory that contains a skills/ subdirectory. After degit, no such subdirectory exists; mogplex-skills/ is the skills tree.
  • cli/skills/index.mdx (Claude Code block) correctly uses cp -R . ~/.claude/skills/ after cd mogplex-skills, acknowledging that the current directory is the skills tree.

For the per-project case in cli/skills/index.mdx, the snippet uses cp -R /path/to/mogplex-skills/* .claude/skills/ with a hardcoded placeholder path, which is less helpful than a relative path or an explicit note to replace it. Consider aligning both pages to the same download-then-copy pattern and making sure the glob targets are consistent.

cd mogplex-skills

# Global
mkdir -p ~/.claude/skills && cp -R skills/* ~/.claude/skills/
mkdir -p ~/.claude/skills && cp -R . ~/.claude/skills/

# Or per-project
mkdir -p .claude/skills && cp -R skills/* .claude/skills/
# Or per-project (run from your project root, not the downloaded skills dir)
mkdir -p .claude/skills && cp -R /path/to/mogplex-skills/* .claude/skills/
```

### Claude Agent SDK
Expand Down
12 changes: 6 additions & 6 deletions content/docs/extend/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,16 +8,16 @@ Mogplex is usable from two surfaces that ship today: the [web app](/web) and the
The core question is: your teammate is in Claude Code, Cursor, or a custom Claude Agent SDK app, and wants to use their Mogplex skills, memories, or agents from there — without pasting tokens into a JSON config. What should they do?

<Cards>
<Card
title="MCP server (preview)"
href="/extend/mcp-server"
description="The Mogplex MCP server — remote Streamable HTTP, OAuth 2.1 + PKCE, no token pasting. Planned; not yet generally available."
/>
<Card
title="Skills (available today)"
href="/extend/skills"
description="Anthropic Agent Skills that teach any skill-aware host how to drive a Mogplex workspace through the `mogplex` CLI. Ships today; the MCP-ready substitute."
/>
<Card
title="MCP server (preview)"
href="/extend/mcp-server"
description="The Mogplex MCP server — remote Streamable HTTP, OAuth 2.1 + PKCE, no token pasting. Planned; not yet generally available."
/>
</Cards>

## Which path is right today
Expand All @@ -38,6 +38,6 @@ Skills are the recommended path until the MCP server is generally available. The

## Design principles this section follows

- **No pasted tokens.** Whether the user picks Skills or MCP, the auth flow owns the credential — either `mogplex login` writing to the OS keyring (Skills path) or OAuth 2.1 + PKCE against the browser session (MCP path).
- **No pasted tokens.** Whether the user picks Skills or MCP, the auth flow owns the credential — either `mogplex login` writing to `~/.mogplex/auth.json` (Skills path) or OAuth 2.1 + PKCE against the browser session (MCP path). In both cases the external agent never sees raw auth material.
- **One source of truth per capability.** Tools, agents, skills, and memories are implemented once in the Mogplex runtime and exposed through whichever surface the host supports. Both paths call the same underlying services.
- **Auth preflight is mandatory.** Both paths require a working credential before any action runs. Skills enforce it with a `command -v mogplex` + `mogplex login status` gate; MCP enforces it at the Streamable HTTP bearer-token middleware.
16 changes: 10 additions & 6 deletions content/docs/extend/mcp-server.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,11 @@ The Mogplex MCP server is in **preview design state** — not generally availabl

## What it is

A remote Model Context Protocol server running at `https://mogplex.com/mcp`. Any MCP-aware agent host (Claude Code, Cursor, Claude Desktop, opencode, custom Agent SDK apps) can connect and call Mogplex tools, agents, skills, and memories as MCP primitives — without the user pasting a token into a JSON config.
A remote Model Context Protocol server hosted by Mogplex. Any MCP-aware agent host (Claude Code, Cursor, Claude Desktop, opencode, custom Agent SDK apps) will be able to connect and call Mogplex tools, agents, skills, and memories as MCP primitives — without the user pasting a token into a JSON config.

<Callout>
The final endpoint path is not yet committed. Examples on this page use `https://mogplex.com/mcp` as a **placeholder**; the shipping URL (exact host, version prefix) will be announced in release notes and this page will be updated then. Do not wire the placeholder URL into production clients.
</Callout>

## What it replaces

Expand Down Expand Up @@ -50,17 +54,17 @@ Mogplex skills are additionally exposed as MCP **prompts**, since a skill defini

## Install (once available)

Remote Streamable HTTP — no shim, no token pasting, the host drives OAuth:
Remote Streamable HTTP — no shim, no token pasting, the host drives OAuth. The shape of the commands below is accurate; the URL is a placeholder that will be finalized when the server ships:

```bash
# Claude Code
claude mcp add --transport http mogplex https://mogplex.com/mcp
# Claude Code — replace <URL> with the final endpoint from release notes
claude mcp add --transport http mogplex <URL>

# Cursor
# Settings → MCP → Add server → URL: https://mogplex.com/mcp
# Settings → MCP → Add server → URL: <URL>
```

For hosts that don't yet speak remote MCP with OAuth, a stdio shim `npx -y @mogplex/mcp` will ship alongside. The shim runs the OAuth flow once, caches the token in the OS keyring, and proxies stdio ↔ HTTP.
For hosts that don't yet speak remote MCP with OAuth, a stdio shim `npx -y @mogplex/mcp` will ship alongside. The shim runs the OAuth flow once, stores the token in `~/.mogplex/auth.json` (same file the CLI uses), and proxies stdio ↔ HTTP.

## How it relates to Connections (inbound MCP)

Expand Down
20 changes: 17 additions & 3 deletions content/docs/extend/skills.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ Together they cover the same capability surface the [MCP server](/extend/mcp-ser

## Why this is the right path today

- **No pasted tokens.** The `mogplex login` browser flow owns the credential and writes it to the OS keyring. The external agent never sees raw auth material.
- **No pasted tokens.** The `mogplex login` browser flow owns the credential and writes it to `~/.mogplex/auth.json` — see the [Authentication guide](/cli/guides/authentication) for precedence rules and file contents. The external agent never sees raw auth material.
- **Works in every skill-aware host.** The skill format is portable: Claude Code, Claude Agent SDK, and any host that reads `SKILL.md`-style files. Cursor project rules work too by copying the skill body.
- **Thin wrapper.** Skills do not duplicate Mogplex logic — they are instructions for how to call the existing CLI, which calls the existing Mogplex runtime.
- **No infra dependency.** Ships the moment the CLI is on the user's `PATH`. Nothing to deploy, no tokens to provision.
Expand All @@ -33,7 +33,7 @@ Together they cover the same capability surface the [MCP server](/extend/mcp-ser
| --- | --- | --- |
| Status | **Available** | Preview design; not live |
| Protocol | Skill file + shell | MCP Streamable HTTP |
| Auth | `mogplex login` → OS keyring | OAuth 2.1 + PKCE (DCR) |
| Auth | `mogplex login` → `~/.mogplex/auth.json` | OAuth 2.1 + PKCE (DCR) |
| Token pasted in config? | No | No |
| Execution path | External agent shells out to `mogplex exec` | External agent calls MCP tool |
| Streaming progress | `--jsonl` | MCP `notifications/progress` |
Expand All @@ -44,8 +44,22 @@ When the MCP server ships, both paths will stay supported. Skills will continue

## Install
Copy link
Copy Markdown

@mogplex mogplex Bot Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion: Option A (git clone) leaves the user inside mogplex-docs/ — the copy command needs skills/*, not skills/

In extend/skills.mdx, Option A clones the whole repo and does cd mogplex-docs. The next code block then runs cp -R skills/* ~/.claude/skills/, which works correctly from that location. This is fine, but a quick inline comment — # run from repo root — would make it unambiguous for users who might cd skills out of habit before running the copy.


First fetch the skill files from [`webrenew/mogplex-docs`](https://github.com/webrenew/mogplex-docs). Either clone the repo or download the `skills/` tree directly:

```bash
# Option A — clone and cd
git clone https://github.com/webrenew/mogplex-docs.git
Copy link
Copy Markdown

@mogplex mogplex Bot Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Critical: Broken shell command: cd mogplex-skills && cd .. undoes the directory change

In extend/skills.mdx, Option B of the new fetch step reads:

npx -y degit webrenew/mogplex-docs/skills mogplex-skills
cd mogplex-skills && cd ..    # or rename the dir as you like

The cd .. immediately reverts the cd mogplex-skills, leaving the user in the original working directory. The next code block then tells readers to run cp -R skills/* ~/.claude/skills/, but after cd .. there is no skills/ subdirectory — degit downloads the contents of skills/ into mogplex-skills/, not a nested skills/ directory. The user will get cp: skills/*: No such file or directory.

The Option A path (git clone … && cd mogplex-docs) leaves the user inside the repo root, so skills/* glob is correct there. For Option B the correct flow should end inside mogplex-skills/ (or the second block should reference mogplex-skills/* from the parent). Suggested fix for Option B:

# Option B — sparse download of just the skills/ tree
npx -y degit webrenew/mogplex-docs/skills mogplex-skills
# The directory is now ready; see copy commands below — run them from the parent, not inside mogplex-skills

Then change the copy block to reference mogplex-skills/* explicitly, or note that the user must cd mogplex-skills first.

cd mogplex-docs

# Option B — sparse download of just the skills/ tree
npx -y degit webrenew/mogplex-docs/skills mogplex-skills
cd mogplex-skills && cd .. # or rename the dir as you like
Comment on lines +55 to +56
Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector Bot Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Make Option B copy path match downloaded tree

If a reader follows Option B (npx -y degit webrenew/mogplex-docs/skills mogplex-skills), the downloaded directory contains the skill folders at its root, not under a skills/ subdirectory. The next install step still tells them to copy skills/*, which will fail (cannot stat 'skills/*') in the documented flow, so the “sparse download” path is currently unusable unless they manually rewrite commands.

Useful? React with 👍 / 👎.

```

Then copy the `skills/` contents into your agent host:

```bash
# Global (Claude Code)
# Global (Claude Code) — run from the directory containing `skills/`
mkdir -p ~/.claude/skills && cp -R skills/* ~/.claude/skills/

# Or per-project
Expand Down