Overview #
When using the Model Context Protocol (MCP) with LearnDash, it’s possible to run into errors—especially during first-time setup or when prompting an AI tool like Cursor or Angie. This guide covers the most common issues and how to fix them.
Most problems are caused by one of the following:
- Authentication issues (e.g., invalid application password)
- Misconfigured prompts
- Server setup problems
- REST API access problems
This guide is intended for both beginner users and site administrators.
Common Errors and How to Fix Them #
1. “401 Unauthorized” or “403 Forbidden” #
What it means:
The MCP server couldn’t authenticate with your site.
Possible causes:
- The application password is incorrect or expired
- The username is incorrect
- The user account doesn’t have administrator permissions
- WordPress REST API is disabled or restricted
How to fix it:
- Regenerate your application password (see [Creating WordPress Application Passwords for MCP])
- Confirm you’re using the correct username (case-sensitive)
- Make sure your WordPress user has administrator access
- Check for security plugins or firewalls that might block REST API requests
2. “Cannot connect to the LearnDash MCP server” (in Cursor) #
What it means:
Cursor can’t reach or communicate with the local MCP server or your site.
Possible causes:
- Local server not started or crashed
- Incorrect site URL
- MCP dependencies not installed
- Firewall or network restrictions
How to fix it:
- Restart the local MCP server inside Cursor
- Verify that your site URL is correct and publicly accessible (if required)
- If prompted, let Cursor install any missing dependencies
- Check for VPN or firewall settings that might be blocking the connection
3. Prompt works, but nothing changes in LearnDash #
What it means:
The AI interpreted the prompt but didn’t take the intended action.
Possible causes:
- The prompt was too vague or unclear
- The content already exists and was skipped
- The LLM misinterpreted field names or relationships
How to fix it:
- Rephrase the prompt using specific course names, field values, and action verbs
- Limit each prompt to 3–5 clear actions
- Use exact names from LearnDash (e.g., “Start Date,” “Access Mode,” etc.)
- Specify whether content should be a draft or published
For tested prompt templates, see the LearnDash AI Prompt Library.
4. “Endpoint not found” or “404 error” #
What it means:
The MCP server is trying to use an API endpoint that your site doesn’t recognize.
Possible causes:
- LearnDash REST API is not enabled
- The plugin version is outdated
- The endpoint requires a special API header
How to fix it:
- Make sure you are running the latest version of LearnDash
- Confirm that the MCP is pointing to a site with REST API v2 support
For some endpoints, add the experimental header:
Learndash-Experimental-Rest-Api: true
- (Developers can refer to the LearnDash MCP Readme for header usage.)
5. The MCP Server starts but fails mid-prompt (Cursor) #
What it means:
The server launched successfully, but an error occurred during processing.
Possible causes:
- The local MCP server crashed or ran out of resources
- The prompt was too long or overly complex
- AI tool lost access to site credentials
How to fix it:
- Break the prompt into smaller, simpler tasks
- Restart the MCP server and Cursor session
- Re-enter the application password if asked
- Monitor your system resources if running large operations locally
General Troubleshooting Tips #
- Always start with a backup before trying new prompts
- Use specific, limited prompts for safer execution
- If unsure, start with test data (test courses, lessons, or users)
- When in doubt, regenerate your application password and try again
Still Not Working? #
If none of the above solutions fix the issue:
- Confirm that you’re using the correct LearnDash API version
- Recheck plugin compatibility (LearnDash, WordPress, any security plugins)
- Try using a staging environment to isolate the problem
- Submit a support ticket if needed.