Troubleshooting

Common issues and solutions when using Promptsy with MCP.

Connection Issues

Tools Not Appearing

Symptoms:

• AI assistant doesn't recognize Promptsy commands
• "I don't have access to that tool" messages

Solutions:

1. Restart the AI assistant

   • Completely quit and reopen Claude Desktop
   • Refresh the ChatGPT page

2. Verify configuration

   • Check the config file syntax (valid JSON)
   • Ensure the URL is correct: https://mcp.promptsy.dev
   • Verify the transport is set to sse

3. Test the server

   curl https://mcp.promptsy.dev/

   Should return: {"status":"ok"}

Authorization Popup Not Showing

Symptoms:

• No redirect to Promptsy consent screen
• Tool calls hang indefinitely

Solutions:

1. Check popup blockers

   • Allow popups from the AI assistant
   • Try in incognito/private window

2. Clear browser cache

   • Clear cookies for promptsy.dev
   • Clear OAuth state

3. Try explicit tool call

   "Use the Promptsy browse_prompts tool"

"Not Authorized" Error

Symptoms:

• AUTH_REQUIRED error code
• "Please authorize first" message

Solutions:

1. Re-authorize

   • Go to Promptsy settings
   • Revoke existing connection
   • Try connecting again

2. Check account status

   • Ensure you're logged into Promptsy
   • Verify email is confirmed

3. Check scopes

   • Make sure required scopes were granted
   • Re-authorize with all scopes

Tool Errors

"Token Expired"

Symptoms:

• TOKEN_EXPIRED error
• Worked before, now fails

Solutions:

Usually automatic—the token should refresh. If it doesn't:

1. Wait a moment and try again
2. Revoke and re-authorize
3. Check your Promptsy session is valid

"Insufficient Scope"

Symptoms:

• INSUFFICIENT_SCOPE error
• Specific tools don't work

Solutions:

1. Check which scope is needed:

   • browse_prompts → prompts:read
   • save_prompt → prompts:write

2. Re-authorize with the required scope

"Limit Reached" (Free Tier)

Symptoms:

• LIMIT_REACHED error when saving
• 25 prompt maximum reached

Solutions:

1. Delete unused prompts
2. Upgrade to Solo tier for unlimited prompts

"Validation Error"

Symptoms:

• VALIDATION_ERROR error
• Tool call fails with parameter issue

Solutions:

1. Check parameter types (strings, arrays)
2. Verify lengths don't exceed limits:
   • Title: 200 characters
   • Description: 500 characters
   • Tags: 10 maximum

Empty Results

No Prompts Showing

Symptoms:

• browse_prompts returns empty
• "You don't have any prompts" message

Solutions:

1. Check your vault

   • Open promptsy.dev/dashboard
   • Verify you have prompts

2. Check the account

   • You might be logged into a different account
   • Re-authorize to verify account

3. Try public search

   "Search public prompts for email"

   If this works, the issue is with your vault access

Search Returns Nothing

Symptoms:

• search_public_prompts returns empty
• Expected results not appearing

Solutions:

1. Try broader search terms
2. Remove category filter
3. Check spelling
4. Try without quotes

Widget Issues

Widget Not Loading

Symptoms:

• Blank space where widget should be
• Loading spinner that never resolves

Solutions:

1. Check internet connection
2. Refresh the conversation
3. Try a different AI client

Copy Button Not Working

Symptoms:

• Click copy, nothing happens
• No "Copied!" confirmation

Solutions:

1. Check clipboard permissions
2. Try keyboard shortcut (Ctrl/Cmd + C)
3. Manually select and copy text

Widget Looks Broken

Symptoms:

• Missing styles
• Overlapping elements
• Unreadable text

Solutions:

1. Clear browser cache
2. Try a different browser
3. Ask for "plain text results" as workaround

Rate Limiting

"Too Many Requests"

Symptoms:

• RATE_LIMITED error
• 429 status code

Solutions:

1. Wait 60 seconds and try again
2. Reduce request frequency
3. Use larger limit values for fewer calls

Configuration Issues

Invalid JSON

Symptoms:

• Claude Desktop won't start
• Config file error messages

Solutions:

1. Validate JSON at jsonlint.com

2. Check for:

   • Missing commas
   • Unmatched brackets
   • Trailing commas (not allowed)

3. Example valid config:

   {
     "mcpServers": {
       "promptsy": {
         "url": "https://mcp.promptsy.dev",
         "transport": "sse"
       }
     }
   }

Wrong File Location

Symptoms:

• Config changes have no effect
• AI assistant uses old configuration

Solutions:

Verify the file location for your OS:

OS	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

Getting Help

If none of these solutions work:

1. Check status page: status.promptsy.dev
2. Community forum: Ask in our Discord
3. Email support: support@promptsy.dev

When contacting support, include:

• AI assistant and version
• Error message (exact text)
• Steps to reproduce
• Time the error occurred

Error Code Reference

Code	Meaning	Common Cause
AUTH_REQUIRED	No authentication	Need to authorize
TOKEN_EXPIRED	Token too old	Should auto-refresh
INSUFFICIENT_SCOPE	Missing permission	Need more scopes
TIER_REQUIRED	Feature needs upgrade	Upgrade plan
CREDITS_EXHAUSTED	No credits left	Wait for refresh or upgrade
LIMIT_REACHED	Hit tier limit	Delete items or upgrade
RATE_LIMITED	Too many requests	Wait and retry
VALIDATION_ERROR	Bad parameters	Check input format
NOT_AUTHORIZED	Can't access resource	Check ownership
PROMPT_NOT_FOUND	Prompt doesn't exist	Check prompt ID
INTERNAL_ERROR	Server issue	Try again later