Skip to main content

​
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

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
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
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
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

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
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
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

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
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
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
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.
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

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
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-..."
});
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
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

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"]
}
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
Symptoms: OAuth flow fails or doesn’t complete.Solutions:
  1. Ensure your MCP client supports OAuth:
  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.

Build docs developers (and LLMs) love

Get started for freeTalk to us