Moxie Docs — MCP & Agent Tools

The Moxie Docs Model Context Protocol (MCP) server, the agent skills Moxie installs into your repository, and the moxie-docs CLI that wires it all up — npx moxie-docs setup.

This repo is also the open-source home of the moxie-docs npm package: a setup CLI plus the MCP interface (tool catalog, prompts, server metadata, and skill renderers) you can import. The hosted server, indexing pipeline, and your generated docs stay in the private Moxie service.

Moxie Docs indexes a connected GitHub repository and keeps its documentation alive — generating docs, discovering conventions, tracking documentation gaps and drift, and opening pull requests that keep docs in sync with code. The MCP server exposes that living context to coding agents (Claude Code, Cursor, VS Code, Codex, and any MCP-capable client) so they ground their work in how your repository actually does things — and keep the docs current as they change code.

• Website / dashboard: https://moxiedocs.com

• Human docs for the MCP server: https://moxiedocs.com/mcp

• MCP endpoint: https://moxiedocs.com/api/mcp

This repository is documentation and distribution assets only. The hosted server, indexing pipeline, and your repositories' documentation are not stored here.

Contents

• Quick start

• CLI

• The MCP server

  • Connection

  • Authentication

  • Client configuration

  • Tools

  • Prompts

• Skills

  • The moxie-docs skill

  • What Moxie installs into your repository

• Use as a library

• Discovery endpoints

• License

Related MCP server: LightRAG Code Brain MCP

Quick start

The fastest path — from your repository's directory:

npx moxie-docs setup

This signs you in (OAuth in your browser), writes the MCP config for your editor, installs the moxie-docs skill + AGENTS.md guidance, and verifies the connection. After that, your agent reads live context with moxie.get_ai_context before editing and proposes doc updates that land in the same PR.

Prefer to do it by hand? Connect a repository at https://moxiedocs.com, then add the server to your agent with a config block.

CLI

The moxie-docs CLI (Node ≥ 18, zero runtime dependencies) sets up and manages the connection. Run it with npx moxie-docs <command> or install it globally (npm i -g moxie-docs).

Useful flags: --client <name>, --token <dashboard-token>, --repo owner/name, --no-browser, --yes.

How authentication is written. By default setup/config write a URL-only server entry and let your editor perform its own OAuth sign-in on first use — so nothing in your committed config expires. The CLI's own browser sign-in (used for status and the setup smoke-test) stores a short-lived token plus a refresh token under ~/.moxie-docs/ (file mode 0600); it is never written into a client config. If you'd rather pin a static Authorization header, pass a long-lived dashboard token with --token and the CLI writes that instead. The CLI never logs token values, and it refuses to overwrite a client config it can't safely parse rather than discarding your other MCP servers.

The MCP server

Connection

All write tools are proposals — Moxie returns the file path and content for you (the agent) to write into your own branch. Moxie never edits your repository directly through MCP, and never merges. Reads return compact, citation-backed context rather than raw code dumps.

Authentication

Bearer token (available today). Create a token in the dashboard and send it as a header:

Authorization: Bearer <MOXIE_TOKEN>

Moxie stores only the token hash (plus an encrypted copy so you can reveal it), a prefix, scope, and a last-used timestamp. You can reveal, rotate, or revoke tokens from the dashboard at any time.

OAuth 2.1 sign-in (for clients that support it). MCP clients that implement the OAuth authorization flow can connect by signing in through the browser instead of pasting a token — the client discovers the server's OAuth metadata, registers itself dynamically (RFC 7591), and obtains a token via the authorization-code + PKCE flow. Discovery documents:

• Protected resource metadata: https://moxiedocs.com/.well-known/oauth-protected-resource

• Authorization server metadata: https://moxiedocs.com/.well-known/oauth-authorization-server

Both authentication paths resolve to the same token model, so either works with the same tools. Connected applications can be reviewed and revoked from the dashboard.

Client configuration

Most agents accept a remote MCP server with a URL and headers. Replace <MOXIE_TOKEN> with a token from the dashboard.

Claude Code — .mcp.json (or claude mcp add):

{
  "mcpServers": {
    "moxie-docs": {
      "url": "https://moxiedocs.com/api/mcp",
      "headers": {
        "Authorization": "Bearer <MOXIE_TOKEN>"
      }
    }
  }
}

Cursor — .cursor/mcp.json:

{
  "mcpServers": {
    "moxie-docs": {
      "url": "https://moxiedocs.com/api/mcp",
      "headers": { "Authorization": "Bearer <MOXIE_TOKEN>" }
    }
  }
}

VS Code — .vscode/mcp.json:

{
  "servers": {
    "moxie-docs": {
      "type": "http",
      "url": "https://moxiedocs.com/api/mcp",
      "headers": { "Authorization": "Bearer <MOXIE_TOKEN>" }
    }
  }
}

Keep tokens out of source control. Reference an environment variable where your client supports it, or paste the token only into local, untracked config.

Tools

All tools are read-only except the two propose_* tools, which return a proposal for the agent to apply in its own branch.

Prompts

The server also exposes MCP prompts that script the common workflows:

Skills

Agent Skills are small, triggered instruction files that teach an agent when and how to use a capability. Moxie publishes one skill, moxie-docs, that wires an agent into the edit-then-document workflow.

The moxie-docs skill

The canonical skill lives in this repo at skills/moxie-docs/SKILL.md and is also served from the website (with a published SHA-256 digest) at:

https://moxiedocs.com/.well-known/agent-skills/moxie-docs/SKILL.md

It tells an agent to read live context before editing (get_ai_context, get_doc_impact), follow the repository's real conventions and verified commands, and propose doc updates/removals that ship in the same PR as the code change — never inventing filler docs.

What Moxie installs into your repository

When Moxie connects a repository it opens one "Add Moxie agent guidance" PR that adds three self-healing, deterministic files (regenerated only when they drift or the repo is renamed — never churning on every index):

The installed skill is the repo-specific variant of skills/moxie-docs/SKILL.md: identical workflow, with your owner/name baked in so multi-repo tokens target the right repository. Everything Moxie writes is deterministic and contains no volatile data — live conventions and commands always come from the MCP server, not the committed file.

Use as a library

The package also exports the open-source MCP interface — the backend-independent contract — so you can build tooling against Moxie without depending on the private server. It carries no secrets and no server logic.

import {
  moxieMcpTools,            // the tool catalog (names, descriptions, input schemas, annotations)
  moxieMcpPrompts,          // the document-this-change / fix-stale-docs prompt descriptors
  moxieMcpServerInfo,       // { name, version }
  moxieMcpProtocolVersion,  // "2025-06-18"
  moxieMcpCapabilities,
  renderSkillMarkdown,      // ({ repository }) => the moxie-docs SKILL.md for a repo
  renderAgentsGuidanceBlock,// ({ repository }) => the AGENTS.md guidance block
  moxieDocsSkillMarkdown,   // the canonical published skill, as a string
  MOXIE_MCP_ENDPOINT,       // "https://moxiedocs.com/api/mcp"
  MOXIE_SITE_URL,
} from "moxie-docs";

What it does not include: the tool handlers, the indexing/doc-generation pipeline, AI/vector-search, the database layer, or token storage — those remain in the hosted Moxie service.

Discovery endpoints

Moxie publishes a small machine-discoverable surface so agents and crawlers can find the server:

License

MIT © Jackalope Dev. The contents of this repository (documentation, skill files, and templates) are open source. The hosted Moxie Docs service, indexing pipeline, and generated documentation are not part of this repository.