Skip to main content
Sign inSign up
Documentation

Troubleshooting

License validation fails

"Invalid credentials" — the license key and the panel secret must be the pair issued together. If you rotated credentials, the plugin still has the old pair: paste the new one. If you only copied one value before leaving the page, rotate to get a fresh pair.

"URL mismatch" — the site calling doesn't match the URL registered in the panel. Common when Moodle sits behind a proxy and $CFG->wwwroot differs from the public hostname, or after a domain change. Update the URL in Organization → Moodle and validate again.

The plugin can't reach the panel at all — your Moodle needs outbound HTTPS. Check curl https://moodlemcp.com from the server and any proxy settings in Moodle.

The site can't be connected

"URL not allowed" — the URL must be public HTTPS with a valid certificate. localhost, private ranges and VPN-only hosts are rejected by design. A staging site works if it's publicly reachable.

Certificate errors — a self-signed or expired certificate fails validation. Fix the certificate; there is no bypass.

The assistant says it has no tools

  • The client hasn't reloaded its MCP configuration. Restart it.
  • The URL is wrong: it must be your organization's subdomain and end in /mcp.
  • With a Bearer key: check the header is exactly Authorization: Bearer mcpk_…, and that the key isn't suspended, revoked or expired.
  • With OAuth: remove the connector and re-authorize.

The assistant sees nothing in Moodle

The key works but the underlying Moodle user has no access to what you're asking about. Roles are the outer boundary — a student key can't list a course's participants. Check which user the key was minted for, and whether the key is restricted to read-only, to specific tools or to specific courses. See Keys & permissions.

Calls started failing after they worked

  • The key was suspended or revoked, in the panel or from the plugin.
  • The credentials were rotated and the plugin hasn't been updated.
  • The Moodle user lost the role the key relies on, or was deleted.
  • The token was deleted in Moodle under Site administration → Server → Web services → Manage tokens.

Organization → Moodle → Usage shows errors per key and per tool, which usually pinpoints it in seconds.

A file won't upload

The URL must return the file, not a page wrapping it. Test with curl -IL <url> from outside your network. Google Drive, Dropbox and GitHub each need a specific URL form — see Uploading files. If the tool is missing entirely, your plugin is too old; update it.

The chat is missing or refuses to answer

  • No MCP key is selected as the AI chat identity in Organization → Moodle.
  • The credit balance can't cover the message — top up in Organization → Credits.
  • You hit the rate limit of 10 messages per minute. Wait a moment.

The organization is locked

The trial ended or a payment failed. Subscribe or fix the payment method in Organization → Billing. Nothing is deleted while locked.

Still stuck

Note the exact error, the key's last 4 characters (never the key itself) and the time it happened, and open an issue at github.com/studiolxd/moodlemcp/issues.