Client setup

For most people, the best way to use MoodleMCP is to connect it to ChatGPT or Claude: it's a one-time setup that takes a couple of minutes and involves no keys at all. Command-line tools and editors come next, for whoever needs them.

Which authentication method each client supports is explained in Connect an assistant.

Before you start: your endpoint

Every client connects to your organization's MCP endpoint:

https://<your-org>.moodlemcp.com/mcp

You don't need to build it by hand: the panel shows it with a copy button in Organization → Moodle, both when you create the connection and any time afterwards. If your admin provisioned you from the plugin, the URL also arrives by email alongside your key.

ChatGPT

ChatGPT connects with Sign in with your Moodle: there's no key to copy.

1. Open ChatGPT's settings and go to the connectors section.
2. In advanced settings, turn on developer mode if it isn't already on — this is what lets you add custom MCP connectors.
3. Create a new connector and paste your endpoint URL.
4. When the browser window opens, choose Sign in with your Moodle, log in with your own Moodle account and approve.
5. In a conversation, turn the connector on from the tools menu and ask something about your Moodle.

Custom connectors require a paid ChatGPT plan, and the exact menu names can vary slightly between versions.

Claude (claude.ai and Claude Desktop)

The same steps work for Claude in the browser (claude.ai) and for the desktop app, both with Sign in with your Moodle:

1. Open Claude's settings and go to Connectors.
2. Choose Add custom connector and paste your endpoint URL.
3. Connecting opens a browser window: choose Sign in with your Moodle, log in on your Moodle and approve.
4. In a conversation, check that the connector is turned on in the tools menu and ask something about your Moodle.

Custom connectors require a paid Claude plan. The connector stays bound to your Moodle identity: to connect as somebody else, remove the connector and re-authorize.

Claude Code

With an MCP key in a Bearer header:

claude mcp add --transport http moodle https://<your-org>.moodlemcp.com/mcp \
  --header "Authorization: Bearer mcpk_..."

If you'd rather not handle keys, add the server without the header and authenticate over OAuth when Claude Code prompts you — it's the same Sign in with your Moodle browser flow.

Cursor

In Cursor's MCP configuration file — .cursor/mcp.json inside the project, or your user's global one:

{
  "mcpServers": {
    "moodle": {
      "url": "https://<your-org>.moodlemcp.com/mcp",
      "headers": { "Authorization": "Bearer mcpk_..." }
    }
  }
}

VS Code

VS Code uses its own format, in .vscode/mcp.json inside the project:

{
  "servers": {
    "moodle": {
      "type": "http",
      "url": "https://<your-org>.moodlemcp.com/mcp",
      "headers": { "Authorization": "Bearer mcpk_..." }
    }
  }
}

Clients that only speak stdio

Bridge with the standard mcp-remote package:

npx mcp-remote https://<your-org>.moodlemcp.com/mcp \
  --header "Authorization: Bearer mcpk_..."

Scripts and CI

Any HTTP client works: send the key as a Bearer header over the Streamable HTTP transport. For automation, mint a dedicated key: read-only, scoped to the tools it needs, and with an expiry. See Keys & permissions.

Keep the key in your secret store, never in the repository. If a key leaks, revoke it in the panel; its next call will be refused.

Checking it works

Ask the assistant something that needs your Moodle, such as "which courses am I enrolled in?". If it says it has no tools, it's almost always because it hasn't reloaded its MCP configuration: restart the client or turn the connector off and back on. Other symptoms are covered in Troubleshooting.