docs: add Extend section for outbound integrations (MCP + Skills) #25
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,43 @@ | ||
| --- | ||
| title: Extend | ||
| description: Reach Mogplex capabilities from outside Mogplex — local agents (Claude Code, Cursor, opencode, Claude Agent SDK) driving a user's workspace, skills, memories, and agents through the CLI today or the Mogplex MCP server when it ships. | ||
| --- | ||
|
|
||
| Mogplex is usable from two surfaces that ship today: the [web app](/web) and the [CLI](/cli). This section covers the third direction: letting *other* agents reach Mogplex. | ||
|
|
||
| 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." | ||
| /> | ||
| </Cards> | ||
|
|
||
| ## Which path is right today | ||
|
|
||
| | If the user's agent host… | Use | | ||
| | --- | --- | | ||
| | Is skill-aware (Claude Code, Agent SDK, Cursor project rules) | [Skills](/extend/skills) | | ||
| | Supports remote MCP with OAuth, and the Mogplex MCP server is live | [MCP server](/extend/mcp-server) | | ||
| | Needs a scripted integration from any shell or CI | `mogplex exec --json "…"` — see the [Exec mode guide](/cli/guides/exec-mode) | | ||
|
|
||
| Skills are the recommended path until the MCP server is generally available. They cover every capability an MCP tool call would — tool execution, slash-command dispatch, skill listings, memory read/write, auth — and they do not require the user to paste a token anywhere. | ||
|
|
||
| ## How this section relates to the rest of the docs | ||
|
|
||
| - **Inbound MCP** (Mogplex *consuming* external MCP servers like Zapier, Notion, Supabase) is configured in [Settings → Connections](/web/settings). That direction is live today. | ||
| - **Outbound MCP** (Mogplex *exposed as* an MCP server to external agents) is covered here at [MCP server](/extend/mcp-server). | ||
| - **CLI Skills** documentation lives under [CLI → Skills](/cli/skills). The [Skills](/extend/skills) page in this section is a pointer; the canonical reference is under CLI. | ||
|
|
||
| ## 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). | ||
|
There was a problem hiding this comment.
This says Useful? React with 👍 / 👎. |
||
| - **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. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,89 @@ | ||
| --- | ||
| title: MCP server (preview) | ||
| description: The Mogplex MCP server exposes Mogplex tools, agents, skills, and memories to any MCP-aware local agent over remote Streamable HTTP, authenticated via OAuth 2.1 + PKCE. Planned; preview state. | ||
| --- | ||
|
|
||
| <Callout type="warn"> | ||
| The Mogplex MCP server is in **preview design state** — not generally available. Use [Skills](/extend/skills) today; this page documents the direction of travel so integrators can plan. | ||
| </Callout> | ||
|
|
||
| ## 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. | ||
|
|
||
| ## What it replaces | ||
|
|
||
| The substitute available today is the **Skills** approach (see [Skills](/extend/skills)). Skills teach an external agent to drive Mogplex through the `mogplex` CLI. The MCP server path replaces that shim with a direct protocol-native integration once the host supports remote MCP with OAuth. | ||
|
There was a problem hiding this comment. Warning: MCP server endpoint URL is a real, potentially premature public commitment The page hard-codes claude mcp add --transport http mogplex https://mogplex.com/mcpIf the final URL differs (e.g., Suggestion: Either (a) use a clearly-placeholder URL like |
||
|
|
||
| ``` | ||
| Claude Code / Cursor ──► mogplex.com/mcp (Streamable HTTP, bearer token) | ||
| │ | ||
| ▼ | ||
| Mogplex tool/agent/skill/memory handlers | ||
| (same code paths the in-app agent uses) | ||
| ``` | ||
|
|
||
| ## Auth model | ||
|
|
||
| Spec-compliant MCP OAuth 2.1 + PKCE, reusing the user's existing Supabase session: | ||
|
|
||
| - `/.well-known/oauth-protected-resource` on the MCP endpoint. | ||
| - `/.well-known/oauth-authorization-server` on the app origin. | ||
| - **Dynamic Client Registration** at `/oauth/register` so each client (Claude Code, Cursor, a custom app) provisions its own `client_id` without the user editing any config. | ||
| - Short-lived access tokens (1h, audience `mcp`), rotating refresh tokens (30d), stored hashed in Supabase. | ||
| - Scopes: `tools:read`, `tools:execute`, `memories:read`, `memories:write`, `agents:run`, `skills:read`, `workspaces:read`. Default grant is read-only; execute and write require explicit consent at the authorize step. | ||
|
|
||
| Users manage active clients from **Settings → Connections → Local agents** (revoke, inspect last-used, see requested scopes). | ||
|
|
||
| ## Tool surface (planned v1) | ||
|
|
||
| Each tool is a thin adapter over an existing Mogplex service, not a new capability: | ||
|
|
||
| - `mogplex_list_workspaces`, `mogplex_get_workspace` | ||
| - `mogplex_list_skills`, `mogplex_get_skill`, `mogplex_run_skill` | ||
| - `mogplex_list_agents`, `mogplex_run_agent` (streamed progress via MCP notifications) | ||
| - `mogplex_search_memories`, `mogplex_add_memory`, `mogplex_edit_memory` | ||
| - `mogplex_list_rules`, `mogplex_get_rule` | ||
| - `mogplex_run_tool` (generic dispatcher) | ||
|
|
||
| Mogplex skills are additionally exposed as MCP **prompts**, since a skill definition maps naturally to that primitive. | ||
|
|
||
| ## Install (once available) | ||
|
|
||
| Remote Streamable HTTP — no shim, no token pasting, the host drives OAuth: | ||
|
|
||
| ```bash | ||
| # Claude Code | ||
| claude mcp add --transport http mogplex https://mogplex.com/mcp | ||
|
|
||
| # Cursor | ||
| # Settings → MCP → Add server → URL: https://mogplex.com/mcp | ||
| ``` | ||
|
|
||
| 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. | ||
|
|
||
| ## How it relates to Connections (inbound MCP) | ||
|
|
||
| Do not confuse the two directions: | ||
|
|
||
| | Direction | Where configured | Who authenticates | | ||
| | --- | --- | --- | | ||
| | **Mogplex consumes an MCP server** (Zapier, Notion, …) | [Settings → Connections](/web/settings) | Mogplex to the external service | | ||
| | **Mogplex exposed as an MCP server** | [Settings → Connections → Local agents](/web/settings) (when live) | External agent to Mogplex | | ||
|
|
||
| Both can be in use at the same time. An agent running outside Mogplex can call the Mogplex MCP server, and Mogplex can turn around and call a Notion MCP connection from within the same logical tool call. | ||
|
|
||
| ## Status | ||
|
|
||
| - Design: approved. | ||
| - Schema, OAuth endpoints, Streamable HTTP handler, stdio shim: planned, not yet merged. | ||
| - Current public substitute: [Skills](/extend/skills) and the [CLI](/cli). | ||
|
|
||
| When the server ships, this page will update with the live endpoints, the final scope list, and the Settings UI screenshot. Subscribe to release notes or watch the [mogplex-cli repo](https://github.com/webrenew/mogplex-cli) for the `@mogplex/mcp` package. | ||
|
|
||
| ## See also | ||
|
|
||
| - [Skills](/extend/skills) — today's substitute | ||
| - [CLI Skills reference](/cli/skills) — canonical skill files | ||
| - [Settings → Connections](/web/settings) — inbound MCP (Mogplex as consumer) | ||
| - [MCP specification](https://modelcontextprotocol.io/specification) | ||
|
There was a problem hiding this comment. Warning: Missing terminal period breaks last sentence of The final sentence of the "How it relates to Connections" section ends without a period:
This is a minor copy issue, but it's at the very end of the file and will be visible to readers. Add the missing period. |
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,4 @@ | ||
| { | ||
| "title": "Extend", | ||
| "pages": ["index", "mcp-server", "skills"] | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,61 @@ | ||
| --- | ||
| title: Skills | ||
| description: Anthropic Agent Skills that teach Claude Code, the Claude Agent SDK, Cursor, opencode, and other skill-aware hosts how to drive a user's Mogplex workspace through the `mogplex` CLI. Available today. | ||
| --- | ||
|
|
||
| Skills are the currently-shipping path for letting an external agent reach a user's Mogplex capabilities. They are the drop-in substitute for the [MCP server](/extend/mcp-server) until that ships. | ||
|
|
||
| <Callout> | ||
| The canonical skill files and the per-skill reference pages live under [CLI → Skills](/cli/skills). This page is the entry point from the Extend section — it describes the shape of the set and the trade-offs versus MCP. Go to [/cli/skills](/cli/skills) for the individual skills. | ||
| </Callout> | ||
|
|
||
| ## What the set covers | ||
|
|
||
| | Skill | Role | | ||
| | --- | --- | | ||
| | [`using-mogplex-cli`](/cli/skills/using-mogplex-cli) | Umbrella. Routes the agent to the right command when the user asks for a Mogplex workspace action. | | ||
| | [`mogplex-exec`](/cli/skills/mogplex-exec) | One-off non-interactive runs with `--json` / `--jsonl` output. | | ||
| | [`mogplex-slash`](/cli/skills/mogplex-slash) | Discover and run Mogplex slash commands from the shell. | | ||
| | [`mogplex-auth`](/cli/skills/mogplex-auth) | Auth preflight, env-var precedence, troubleshooting decision tree. | | ||
|
|
||
| Together they cover the same capability surface the [MCP server](/extend/mcp-server) will expose — tool execution, slash-command dispatch, skill and memory access, agent runs, and auth — without needing the host to speak MCP or hold a bearer token. | ||
|
|
||
| ## 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. | ||
| - **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. | ||
|
|
||
| ## Skills vs MCP server at a glance | ||
|
|
||
| | | Skills (today) | MCP server (preview) | | ||
| | --- | --- | --- | | ||
| | Status | **Available** | Preview design; not live | | ||
| | Protocol | Skill file + shell | MCP Streamable HTTP | | ||
| | Auth | `mogplex login` → OS keyring | 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` | | ||
| | Host requirement | Skill-aware (Claude Code, Agent SDK, Cursor rules) | Remote-MCP-aware with OAuth | | ||
| | Host reach today | High | Claude Code ≥ latest, Cursor, a few others | | ||
|
|
||
| When the MCP server ships, both paths will stay supported. Skills will continue to be the right answer for hosts that don't speak remote MCP, for CI contexts, and for anyone who prefers shell-driven integration. | ||
|
|
||
| ## Install | ||
|
|
||
| ```bash | ||
| # Global (Claude Code) | ||
| mkdir -p ~/.claude/skills && cp -R skills/* ~/.claude/skills/ | ||
|
|
||
| # Or per-project | ||
| mkdir -p .claude/skills && cp -R skills/* .claude/skills/ | ||
| ``` | ||
|
There was a problem hiding this comment. Warning: Install snippet references a The install block in cp -R skills/* ~/.claude/skills/This assumes a Suggestion: Add a short prerequisite step above the snippet (e.g., "First, clone the mogplex-docs repo or download the skills archive:") or change the snippet to use a direct download/ |
||
|
|
||
| See [CLI → Skills](/cli/skills) for Agent SDK integration, Cursor instructions, and the full install matrix. | ||
|
|
||
| ## See also | ||
|
|
||
| - [CLI → Skills](/cli/skills) — canonical reference for every skill | ||
| - [MCP server (preview)](/extend/mcp-server) — what Skills are a substitute for | ||
| - [Extend overview](/extend) — the decision between Skills and MCP | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,5 @@ | ||
| { | ||
| "title": "Mogplex Docs", | ||
| "root": true, | ||
| "pages": ["index", "cli", "web", "extend"] | ||
|
There was a problem hiding this comment. Suggestion: The updated <Card title="MCP server (preview)" … />
<Card title="Skills (available today)" … />Since Skills is the recommended path today and MCP is explicitly preview-only, putting it second in the hub card list may cause users to skip the preferred path. Consider swapping the card order so Skills appears first, consistent with the recommendation text that immediately follows the cards. |
||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Suggestion: Exec-mode guide link in
extend/index.mdxdecision table may be a dead linkThe decision table row for CI/shell users links to
/cli/guides/exec-mode. This path is not among the changed files and was not verified in this PR. If that page does not yet exist in the docs, the link will 404. Confirm the target exists or stub it before merging, sincepnpm buildgenerating 168 pages doesn't necessarily validate that every internal anchor resolves.