Troubleshooting

Common issues and solutions for Context7

Overview

This guide covers common issues you might encounter with Context7 MCP server and SDK, along with solutions.

Most issues can be resolved by checking your MCP server configuration and API key setup.

Installation Issues

MCP server not appearing in Cursor

Symptoms: Context7 doesn’t show up in Cursor’s MCP server list.

Solutions:

1. Verify your ~/.cursor/mcp.json configuration:

   {
     "mcpServers": {
       "context7": {
         "url": "https://mcp.context7.com/mcp",
         "headers": {
           "CONTEXT7_API_KEY": "YOUR_API_KEY"
         }
       }
     }
   }
   

2. Check for JSON syntax errors (trailing commas, missing quotes)

3. Restart Cursor completely

4. Try the local server connection instead:

   {
     "mcpServers": {
       "context7": {
         "command": "npx",
         "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]
       }
     }
   }
   

5. Check Cursor’s MCP logs in Settings > Output > Model Context Protocol

Context7 not working in Claude Code

Symptoms: claude mcp add command fails or Context7 doesn’t work.

Solutions:

1. Verify the command syntax:

   claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp --api-key YOUR_API_KEY
   

2. Check Claude Code version (requires Claude Code 1.0+)

3. Try the remote server connection:

   claude mcp add --scope user --header "CONTEXT7_API_KEY: YOUR_API_KEY" --transport http context7 https://mcp.context7.com/mcp
   

4. List MCP servers to verify installation:

   claude mcp list
   

5. Check logs:

   claude mcp logs context7
   

npm/npx errors during installation

Symptoms: npx @upstash/context7-mcp fails with errors.

Solutions:

1. Update npm:

   npm install -g npm@latest
   

2. Clear npm cache:

   npm cache clean --force
   

3. Try installing globally first:

   npm install -g @upstash/context7-mcp
   

4. Check Node.js version (requires Node 18+):

   node --version
   

5. Use the remote server connection to avoid npm issues

Using ctx7 setup command fails

Symptoms: npx ctx7 setup fails or doesn’t configure properly.

Solutions:

1. Ensure you’re running the latest version:

   npx ctx7@latest setup
   

2. Try targeting a specific client:

   npx ctx7 setup --cursor
   npx ctx7 setup --claude
   npx ctx7 setup --opencode
   

3. Use an existing API key instead of OAuth:

   npx ctx7 setup --api-key YOUR_API_KEY
   

4. Check file permissions on config directories

5. Run with verbose output to see detailed errors

API Key Issues

Invalid API key error

Symptoms: “Invalid API key” or “Unauthorized” errors.

Solutions:

1. Verify your API key format (should start with ctx7sk-)
2. Check for extra spaces or quotes around the key
3. Get a new API key from context7.com/dashboard
4. Ensure the key is in the correct configuration field:
   • Remote: headers.CONTEXT7_API_KEY
   • Local: --api-key argument
5. Try regenerating your API key on the dashboard

Rate limit exceeded

Symptoms: “Rate limit exceeded” errors.

Solutions:

1. Get an API key if you’re using Context7 without one
2. Upgrade your plan at context7.com/dashboard
3. Reduce the frequency of requests
4. Implement caching in SDK usage:
   const cache = new Map();
   const cacheKey = `${libraryId}:${query}`;
   if (cache.has(cacheKey)) {
     return cache.get(cacheKey);
   }
   
5. Wait a few minutes before retrying

API key not being used

Symptoms: Context7 works but shows free tier limits.

Solutions:

1. Verify the key is in the correct location in your config
2. Restart your MCP client after adding the key
3. Check that the header name is exactly CONTEXT7_API_KEY
4. For local connections, ensure --api-key flag is present
5. Check MCP server logs to see if the key is being sent

Query and Response Issues

Context7 returns wrong library

Symptoms: Getting documentation for a different library than requested.

Solutions:

1. Use the library ID syntax:

   use library /owner/repository for API and docs
   

2. Be more specific in your prompt:

   # Less specific
   How do I use React?
   
   # More specific  
   How do I use hooks in React 18?
   

3. Check if the library exists on context7.com

4. Verify the library ID format:

   • Correct: /facebook/react
   • Incorrect: facebook/react, /react, React

Getting outdated documentation

Symptoms: Documentation doesn’t match current library version.

Solutions:

1. Specify the version in your prompt:

   How do I use Next.js 14 middleware? use context7
   

2. Request latest version explicitly:

   Show me the latest authentication methods for Supabase. use context7
   

3. Report the issue on context7.com to trigger a re-crawl

4. Check when the library was last updated on Context7

No results or empty response

Symptoms: Context7 returns no documentation.

Solutions:

1. Check if the library is indexed on context7.com

2. Try a broader search:

   # Too specific
   How do I use the obscureFunction in library X?
   
   # Better
   Show me authentication examples for library X
   

3. Search for the library first:

   const libraries = await client.searchLibrary(
     "authentication",
     "supabase"
   );
   console.log(libraries); // Check if library exists
   

4. Submit the library if it’s not indexed: See Adding Libraries guide

Context7 not being invoked automatically

Symptoms: Rule is set up but Context7 doesn’t activate.

Solutions:

1. Verify your rule configuration:

   • Cursor: Settings > Rules
   • Claude Code: Check CLAUDE.md exists

2. Make the rule more explicit:

   You MUST use Context7 MCP for any question about libraries, frameworks, or APIs.
   

3. Restart your MCP client

4. Temporarily add use context7 manually while debugging

5. Check if other rules are conflicting

See the Using Rules guide for detailed setup.

Slow response times

Symptoms: Context7 takes a long time to respond.

Solutions:

1. Use library IDs to skip search step:

   use library /vercel/next.js for API and docs
   

2. Switch to remote server if using local:

   {
     "url": "https://mcp.context7.com/mcp"
   }
   

3. Check your internet connection

4. Verify API key is being used (authenticated requests are faster)

5. Try during off-peak hours if experiencing widespread slowness

SDK Issues

SDK import errors

Symptoms: Cannot import Context7 SDK.

Solutions:

1. Verify installation:

   npm list @upstash/context7-sdk
   

2. Reinstall the SDK:

   npm install @upstash/context7-sdk
   

3. Check import syntax:

   // Correct
   import { Context7 } from "@upstash/context7-sdk";
   
   // Incorrect
   import Context7 from "@upstash/context7-sdk";
   

4. Ensure TypeScript/Node version compatibility

5. Clear node_modules and reinstall:

   rm -rf node_modules package-lock.json
   npm install
   

Environment variable not loading

Symptoms: CONTEXT7_API_KEY env var not found.

Solutions:

1. Verify .env file location (should be in project root)

2. Load env vars in your code:

   import 'dotenv/config';
   import { Context7 } from "@upstash/context7-sdk";
   

3. Check env var name (must be exactly CONTEXT7_API_KEY)

4. Restart your development server after adding env vars

5. Pass API key directly if env vars aren’t working:

   const client = new Context7({
     apiKey: "ctx7sk-..."
   });
   

TypeScript type errors

Symptoms: Type errors when using the SDK.

Solutions:

1. Ensure SDK types are installed:

   npm install --save-dev typescript @types/node
   

2. Check SDK version (update to latest):

   npm update @upstash/context7-sdk
   

3. Use proper types:

   const docs: Array<{ title: string; content: string; url: string }> = 
     await client.getContext(query, libraryId);
   

4. Check TypeScript version compatibility

SDK timeout errors

Symptoms: Requests timing out.

Solutions:

1. Increase timeout (SDK default is usually sufficient):

   const client = new Context7({
     apiKey: process.env.CONTEXT7_API_KEY,
     // Custom fetch with timeout if needed
   });
   

2. Check network connectivity

3. Verify Context7 API status

4. Try with a simpler query to isolate the issue

5. Use library IDs to speed up queries

Connection Issues

Remote server connection fails

Symptoms: Cannot connect to https://mcp.context7.com/mcp.

Solutions:

1. Check internet connectivity

2. Verify the URL is correct (no typos)

3. Try the OAuth endpoint:

   {
     "url": "https://mcp.context7.com/mcp/oauth"
   }
   

4. Check if your firewall is blocking the connection

5. Try local server connection as fallback:

   {
     "command": "npx",
     "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]
   }
   

Local server connection fails

Symptoms: Local MCP server won’t start.

Solutions:

1. Verify Node.js is installed:

   node --version
   

2. Check npm can access the package:

   npx -y @upstash/context7-mcp --help
   

3. Clear npx cache:

   rm -rf ~/.npm/_npx
   

4. Try installing globally:

   npm install -g @upstash/context7-mcp
   

   Then use:

   {
     "command": "context7-mcp",
     "args": ["--api-key", "YOUR_API_KEY"]
   }
   

5. Switch to remote server connection

OAuth authentication issues

Symptoms: OAuth flow fails or doesn’t complete.

Solutions:

1. Ensure your MCP client supports OAuth:

   • Check MCP OAuth specification

2. Verify OAuth endpoint URL:

   {
     "url": "https://mcp.context7.com/mcp/oauth"
   }
   

3. Clear browser cookies and try again

4. Use API key authentication instead:

   {
     "url": "https://mcp.context7.com/mcp",
     "headers": {
       "CONTEXT7_API_KEY": "YOUR_API_KEY"
     }
   }
   

5. Contact Context7 support if OAuth is required for your use case

Getting Help

If you’re still experiencing issues:

Check Documentation

Browse the full Context7 documentation.

Join Discord

Get help from the community.

GitHub Issues

Report bugs or request features.

Contact Support

Reach out to the Context7 team.

Diagnostic Checklist

Before reporting an issue, gather this information:

1. MCP client and version

   • Which client? (Cursor, Claude Code, etc.)
   • Version number
2. Connection type

   • Remote or local server?
   • Full configuration (with API key redacted)
3. Error messages

   • Complete error text
   • MCP server logs
   • Client logs
4. Steps to reproduce

   • Exact prompt or code used
   • Expected vs actual behavior
5. Environment

   • Operating system
   • Node.js version (if using local server)
   • Network setup (proxy, VPN, firewall)

Having this information ready will help maintainers and community members assist you faster.

Next Steps

Best Practices

Learn how to use Context7 effectively.

Using Rules

Set up automatic Context7 invocation.