Use the Moxie Docs MCP skill

Overview

Connect an MCP-compatible agent to your Moxie Docs repository so the agent can call repository-aware prompts to document changes and fix stale docs. After setup, you can invoke the document-this-change and fix-stale-docs prompts with repository context and receive actionable outputs, plus trace IDs for feedback.

This guide shows how to connect, configure basic options, and verify the integration using real prompt calls.

Before you start

• A Moxie Docs workspace with at least one GitHub repository connected and indexed.
• Access to the Moxie Docs dashboard with permission to view Docs and Opportunities.
• An MCP-compatible agent or client (for example, an MCP runtime in your local dev environment or a hosted agent) that supports tool schemas and prompt invocation.
• A project where you can add MCP server configuration files (e.g., agent config JSON/YAML).

Connect

1. Open Moxie Docs and go to Dashboard → Docs to confirm your repository is connected and searchable via the Ask panel.

2. Navigate to your MCP agent’s configuration file (for example, mcp.config.json).

3. Add the Moxie Docs MCP skill as a tool source. Use a descriptive name like moxie-docs and point your agent to the Moxie Docs MCP endpoint exposed for your workspace. Example JSON snippet:

   {
     "tools": {
       "moxie-docs": {
         "type": "mcp",
         "transport": "http",
         "baseUrl": "https://app.moxiedocs.com/mcp",
         "headers": {
           "X-Moxie-Workspace": "your-workspace-id",
           "Authorization": "Bearer YOUR_AGENT_TOKEN"
         }
       }
     }
   }
   

4. Save the configuration and restart your MCP agent so it loads the new tool.

5. List tools from your agent shell or UI and confirm moxie-docs (or your chosen name) is available with prompts document-this-change and fix-stale-docs.

Note: Use your agent’s standard method for configuring MCP tools. Names and file paths vary by client. The base URL and headers must match your workspace. Do not share tokens publicly.

Configure

Configure how the prompts run against your repository context:

• Repository selector: Explicitly specify which connected repo to target (e.g., owner/repo). If omitted, the skill uses your workspace default if exactly one repo is connected.
• Branch or ref: Provide a branch like main or a full ref so changes and suggestions align with current docs.
• Path scope: Limit to a directory or file glob (e.g., docs/ or packages/app/**) to keep runs focused.
• Change context: For documenting recent updates, pass commit SHAs, a PR number, or a diff patch to ground the analysis.
• Output mode: Choose between inline suggestions, patch-like diffs, or a structured task list to drive a follow-up docs PR.
• Feedback capture: Keep the traceId from responses so you can send quality feedback via thumbs up/down with optional tags and comments from the dashboard.

Verify it works

1. Run document-this-change with a single commit:

   {
     "tool": "moxie-docs",
     "prompt": "document-this-change",
     "params": {
       "repo": "owner/repo",
       "ref": "main",
       "commits": ["abc1234"],
       "pathScope": "docs/",
       "output": "diff"
     }
   }
   

   Expect a response containing suggested docs updates and a traceId.

2. Run fix-stale-docs scoped to a package:

   {
     "tool": "moxie-docs",
     "prompt": "fix-stale-docs",
     "params": {
       "repo": "owner/repo",
       "ref": "main",
       "pathScope": "packages/api/**",
       "output": "tasks"
     }
   }
   

   Expect detected stale pages, deletions for orphans where applicable, and grouped fixes.

3. Open Moxie Docs → Docs → Ask and submit a question referencing the same area. Confirm the answer references current code/docs and shows a feedback row with 👍 👎 and a visible trace ID in the details.

4. Check Dashboard suggestions and Opportunities. If you apply generated fixes, you should see them packaged as reviewable, docs-only PRs. Status will reconcile in the suggestions UI. Moxie never auto-merges.

Disconnect or change access

• To change repository scope: Update your MCP tool repo, ref, or pathScope parameters in the agent configuration and restart the agent.
• To rotate credentials: Replace the Authorization token in your MCP tool headers and restart the agent.
• To disconnect entirely: Remove the moxie-docs tool block from your agent configuration and restart. Optionally, in Moxie Docs, revoke access by removing the GitHub repository or adjusting team permissions.

For ongoing cleanup automation or PR templating, manage options from the Dashboard using Docs PR Automation features. The integration only generates reviewable PRs and never merges automatically.