hub-mcp

An MCP server that lets an AI assistant (Claude Code, Claude Desktop, or any MCP client) operate an academy hub — the open-source LMS, lead engine and content platform. Through it an assistant can stand up cohorts, edit courses and lessons, work leads, author drip email, manage memberships and run venue events, with the same rules the hub's admin UI enforces.

It is a thin, stdio-only adapter. Every read and write goes to the hub's authenticated internal API (/api/internal/mcp/v1/*); no business logic lives here and nothing touches the hub's database directly.

Install

Requires Node.js 18 or newer to run, and bun to build. Build it once from source:

git clone https://github.com/AiStartAcademy/hub-mcp.git
cd hub-mcp
bun install
bun run build      # writes dist/index.js

MCP clients then launch node /absolute/path/to/hub-mcp/dist/index.js. An npm package (npx -y @aistartacademy/hub-mcp) is coming; the examples below will switch to it then.

The server speaks JSON-RPC over stdin/stdout and logs only to stderr, so you would not normally run it by hand.

Related MCP server: ghl-internal-cli

Configure

The server checks its configuration on launch and exits with a clear message if something is missing or invalid, instead of failing on the first tool call.

Claude Code

claude mcp add hub \
  -e HUB_BASE_URL=https://hub.example.com \
  -e HUB_MCP_TOKEN=your-token \
  -- node /absolute/path/to/hub-mcp/dist/index.js

or in a project .mcp.json:

{
  "mcpServers": {
    "hub": {
      "command": "node",
      "args": ["/absolute/path/to/hub-mcp/dist/index.js"],
      "env": {
        "HUB_BASE_URL": "https://hub.example.com",
        "HUB_MCP_TOKEN": "${HUB_MCP_TOKEN}",
        "HUB_MCP_READONLY": "true"
      }
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "hub": {
      "command": "node",
      "args": ["/absolute/path/to/hub-mcp/dist/index.js"],
      "env": {
        "HUB_BASE_URL": "https://hub.example.com",
        "HUB_MCP_TOKEN": "your-token"
      }
    }
  }
}

A common setup is two entries pointing at the same build: one for a local or staging hub with writes on, and one for production with HUB_MCP_READONLY=true until you need it.

Set up the hub side

The token and the authoritative write switch both live on the hub.

1. Mint a token. Generate a long random value dedicated to this server, for example openssl rand -hex 32. Do not reuse any other service token.

2. Give it to the hub as HUB_MCP_TOKEN, either in the hub's environment or, if your hub has the admin Settings → Integrations store, there (the stored value wins over the environment and can be rotated without a redeploy). If the hub has no token configured, every MCP route fails closed.

3. Decide on writes. The hub only accepts MCP writes when its own HUB_MCP_WRITES_ENABLED is exactly true. Missing or any other value returns 403 on every write while reads keep working.

4. Give the same token to this server as HUB_MCP_TOKEN (see Configure). Keep it in your MCP client's secret store or environment, never in a committed file.

To rotate, set a new value on the hub, then update the client. To cut off the server entirely, unset or change the hub's token.

How writes work

Every tool that changes data is a two-step write:

1. The first call is a dry run (dryRun defaults to true). It validates the request, shows exactly what would change, and returns a previewId. It writes nothing.

2. A second call with previewId and confirm: true commits. It sends the stored preview, not whatever arguments come with the confirm call, so a model cannot change the payload between preview and commit.

Previews are single-use and expire after 10 minutes. For tools that email or text people (broadcast_send, certificate_notify, instructor_outreach), the preview renders the real message and recipient list; that render is the human approval, so read it.

A few one-step actions skip the preview because they change nothing a student sees: media_upload, program_cover_generate (costs money per call), lesson_audio_extract, and the sync/nudge/gcal_sync actions of the instructor tools. They are still refused under HUB_MCP_READONLY=true and by the hub-side switch.

One default to know about: venue_event_create creates events as APPROVED unless told otherwise, and committing an APPROVED event emails the organizer a confirmation. Pass status: "PENDING" when the booking is not yet agreed. Sending an agreement or a payment link reaches a real organizer, and there is no void endpoint.

Other guarantees: new cohorts are always created as DRAFT; there are no hard-delete tools (archive through status fields instead; zoom_meeting_delete removes a Zoom meeting, not a hub record); and a hub that cannot be reached is reported as an error, never as success.

Read-only kill switches

There are two, and they are independent:

• HUB_MCP_READONLY=true on this server refuses every commit locally. It is a convenience: anyone holding the token can bypass it by calling the hub directly.

• HUB_MCP_WRITES_ENABLED on the hub is the authoritative switch. Unless it is exactly true, the hub rejects every write no matter which client sends it.

Run production read-only by default and enable writes deliberately.

Tools

Generated from the tools the server registers (bun run docs:tools).

40 tools.

Cohorts & sessions

Instructors

Courses, lessons & media

Leads (CRM)

Email & messaging

Memberships

Venue events

Security notes

This server acts with the hub owner's authority, and the caller is a language model. Treat it accordingly.

• Dedicated credential. HUB_MCP_TOKEN is used for nothing else. Rotate and revoke it independently, and never paste it into a tool argument or a prompt.

• Configuration is not user input. HUB_BASE_URL and the token come only from the environment and are read once at startup.

• Hub content is untrusted. Lead notes, lesson text and email bodies returned by tools can contain prompt-injection attempts. They are data, not instructions.

• Reads can contain personal data. Lead, roster and registration tools return names, emails and attendance. Tool output is visible to your model provider and may be logged by your MCP client; scope who can use a server pointed at production.

• stdout is the protocol. All diagnostics go to stderr; never add logging to stdout.

• Local trust. Stdio keeps the server off the network, but it does not sandbox the process. Anyone who can run commands as your OS user can read the token from its environment.

• No HTTP transport. Only stdio is supported. Exposing it over HTTP needs proper OAuth, origin checks and per-user tokens, which this release does not provide.

Report vulnerabilities privately via GitHub security advisories on this repository rather than in a public issue.

Compatibility

Built against the public hub v1 MCP API. Notes for this release:

• cohort_create and zoom_meeting_delete call the hub's pre-v1 routes /api/internal/mcp/cohort and /api/internal/mcp/cohort/zoom; all other tools use /api/internal/mcp/v1/*.

• session_series_create accepts an optional location for hybrid calls. Hubs that predate session-series locations accept the request and ignore the field.

Develop

bun install
bun run typecheck
bun test
bun run build                 # → dist/index.js, runs under plain Node 18+
bun run dev                   # run from source over stdio
bun run docs:tools            # regenerate the tool table above from dist/

See CONTRIBUTING.md.

License

MIT