diff --git a/content/docs/cli/skills/index.mdx b/content/docs/cli/skills/index.mdx index c956b3e..ac1457a 100644 --- a/content/docs/cli/skills/index.mdx +++ b/content/docs/cli/skills/index.mdx @@ -5,6 +5,8 @@ description: Agent Skills that teach external agents (Claude Code, Claude Agent Mogplex ships a set of [Anthropic Agent Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills) that let any skill-aware agent operate a user's Mogplex workspace through the CLI, without MCP, and without asking the user to paste tokens into a JSON config. +This page is the reference for the skill set itself. For the decision between Skills and the upcoming [MCP server](/extend/mcp-server), see [Extend → Skills vs MCP](/extend/skills). + ## Source of truth The canonical skill files live in the docs repo at `skills//SKILL.md` and follow the standard Anthropic skill format (YAML frontmatter with `name` and `description`, markdown body, file named `SKILL.md` in a directory that matches the skill name). diff --git a/content/docs/extend/index.mdx b/content/docs/extend/index.mdx new file mode 100644 index 0000000..7f9def8 --- /dev/null +++ b/content/docs/extend/index.mdx @@ -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? + + + + + + +## 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). +- **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. diff --git a/content/docs/extend/mcp-server.mdx b/content/docs/extend/mcp-server.mdx new file mode 100644 index 0000000..3f7edc2 --- /dev/null +++ b/content/docs/extend/mcp-server.mdx @@ -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. +--- + + +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. + + +## 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. + +``` +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) diff --git a/content/docs/extend/meta.json b/content/docs/extend/meta.json new file mode 100644 index 0000000..be0f3cf --- /dev/null +++ b/content/docs/extend/meta.json @@ -0,0 +1,4 @@ +{ + "title": "Extend", + "pages": ["index", "mcp-server", "skills"] +} diff --git a/content/docs/extend/skills.mdx b/content/docs/extend/skills.mdx new file mode 100644 index 0000000..b081754 --- /dev/null +++ b/content/docs/extend/skills.mdx @@ -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. + + +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. + + +## 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/ +``` + +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 diff --git a/content/docs/index.mdx b/content/docs/index.mdx index c5693fd..7002862 100644 --- a/content/docs/index.mdx +++ b/content/docs/index.mdx @@ -27,6 +27,11 @@ The first useful question is simpler: href="/web" description="Projects, sandboxes, agents, automations, triggers, observability, settings, installations, and the hosted API." /> + In practice, most users do this: diff --git a/content/docs/meta.json b/content/docs/meta.json index 9e48bad..3ba5918 100644 --- a/content/docs/meta.json +++ b/content/docs/meta.json @@ -1,5 +1,5 @@ { "title": "Mogplex Docs", "root": true, - "pages": ["index", "cli", "web"] + "pages": ["index", "cli", "web", "extend"] } diff --git a/content/docs/web/settings.mdx b/content/docs/web/settings.mdx index aa71e64..a1d6054 100644 --- a/content/docs/web/settings.mdx +++ b/content/docs/web/settings.mdx @@ -127,6 +127,10 @@ work?** Connections are where you register the non-model systems agents can call. + +Connections is about **inbound** integrations — Mogplex calling external systems. For the opposite direction — external agents calling into Mogplex — see [Extend](/extend): Skills today, the [MCP server](/extend/mcp-server) in preview. + + Mogplex supports two connection categories: - **REST API** connections