docs/usage.mdx

---
title: How-To Guides
---

Practical techniques for using Context7 effectively.

## Quick Wins

- [Auto-invoke Context7](#auto-invoke-context7) so you never forget to pull fresh docs
- [Target the exact library ID](#use-specific-library-ids) to skip search steps
- [Tune networking and proxies](#configure-https-proxy) for locked-down environments
- [Bring in private repositories](#work-with-private-repositories) for internal docs

## Auto-Invoke Context7

Stop adding `use context7` to every prompt by setting up an automatic rule.

### Add a Rule to Your MCP Client

<AccordionGroup>
  <Accordion title="Cursor" icon="code">
    1. Open `Cursor Settings` → `Rules`
    2. Add this rule:

    ```txt
    Always use context7 when I need code generation, setup steps, or library documentation.
    Automatically use Context7 MCP tools without me having to ask.
    ```

  </Accordion>

  <Accordion title="Windsurf" icon="wind">
    Create or edit `.windsurfrules` in your project root:

    ```txt
    Use context7 for all code generation and API documentation questions.
    ```

  </Accordion>

  <Accordion title="Claude Code" icon="code">
    Create or edit `CLAUDE.md` in your project root:

    ```txt
    Automatically use context7 for code generation and library documentation.
    ```

  </Accordion>
</AccordionGroup>

<Tip>
  Customize the rule for your workflow. Examples: "Auto-invoke only for Next.js questions" or "Use
  context7 when the prompt mentions 'API' or 'documentation'."
</Tip>

## Use Specific Library IDs

Skip the search step and get documentation instantly by specifying exact library IDs.

### How to Find Library IDs

1. Visit [context7.com](https://context7.com)
2. Search for your library
3. The ID is shown in the format `/owner/repository`

### Use in Your Prompts

```txt
Implement JWT auth with Supabase. use library /supabase/supabase
```

```txt
Build a rate limiter. use library /upstash/ratelimit
```

```txt
Set up Next.js middleware. use library /vercel/next.js/v15.1.0
```

<Note>You can even specify versions: `/owner/repo/v1.0.0`</Note>

### Benefits

- **Faster**: No library resolution needed
- **Precise**: Get docs for the exact library and version
- **Reliable**: No ambiguity about which library to use

## Configure HTTPS Proxy

If you're behind a corporate proxy, configure Context7 to route through it.

### Set Environment Variables

<AccordionGroup>
  <Accordion title="Linux/macOS" icon="terminal">
    ```bash
    export https_proxy=http://proxy.example.com:8080
    export HTTPS_PROXY=http://proxy.example.com:8080
    ```

    With authentication:
    ```bash
    export https_proxy=http://username:password@proxy.example.com:8080
    ```

  </Accordion>

  <Accordion title="Windows (Command Prompt)" icon="windows">
    ```cmd
    set https_proxy=http://proxy.example.com:8080
    set HTTPS_PROXY=http://proxy.example.com:8080
    ```

    With authentication:
    ```cmd
    set https_proxy=http://username:password@proxy.example.com:8080
    ```

  </Accordion>

  <Accordion title="Windows (PowerShell)" icon="windows">
    ```powershell
    $env:https_proxy = "http://proxy.example.com:8080"
    $env:HTTPS_PROXY = "http://proxy.example.com:8080"
    ```
  </Accordion>
</AccordionGroup>

### Or Configure in MCP Settings

Add proxy directly to your MCP configuration:

```json
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"],
      "env": {
        "https_proxy": "http://proxy.example.com:8080",
        "HTTPS_PROXY": "http://proxy.example.com:8080"
      }
    }
  }
}
```

Both lowercase and uppercase environment variables are supported.

<Tip>
  After updating proxy settings, run `curl https://mcp.context7.com/mcp/ping` to confirm outbound
  connectivity before restarting your IDE.
</Tip>

## Work with Private Repositories

Add your private GitHub, GitLab, or Bitbucket repositories to make internal documentation available through Context7. Requires a Pro or Enterprise plan.

For complete instructions on adding, refreshing, and managing private repositories, see the [Private Repositories](/dashboard/private-repositories) guide.

**Cost**: $15 per 1M tokens when parsing. See [Plans & Pricing](/plans-pricing) for details.

## Set Up Team Collaboration

Share Context7 access with your team. Create a team, invite members with different roles (Owner, Admin, Developer), and manage permissions from your dashboard.

For complete instructions on creating teams, inviting members, and managing roles, see the [Team Management](/dashboard/team) guide.

**Cost**: $7 per team member per month on Pro plan. See [Plans & Pricing](/plans-pricing) for details.

## Refresh Library Documentation

Keep your documentation up to date.

### Web Interface

1. Go to [context7.com/refresh-library](https://context7.com/refresh-library)
2. Enter library ID (e.g., `/vercel/next.js`)
3. Submit

### API

```bash
POST https://context7.com/api/v1/refresh
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "docsRepoUrl": "https://github.com/vercel/next.js"
}
```

### When to Refresh

- After major version releases
- When documentation is updated
- When you notice outdated information

<Note>For private repos, you only pay for new/changed content during refresh.</Note>

## Monitor Usage

Track your API usage, parse tokens, and costs from the dashboard. View metrics for search requests, query tokens, parse tokens, and total monthly costs with detailed breakdowns.

For complete details on usage statistics and cost calculations, see the [Usage Statistics](/dashboard/usage) guide.

## Best Practices

### Security

- Never commit API keys to version control. Use `.env` files and add them to `.gitignore`.
- Use environment variables for keys, like: `export CONTEXT7_API_KEY=your_key_here`.
- Rotate keys regularly -- every 90 days or immediately if compromised.
- Grant only the permissions a team member needs. Use the "Developer" role for non-admins.

See [Security](/security) for comprehensive security guidelines.

### Performance

- Use specific library IDs such as `/vercel/next.js` instead of general phrases like "next.js docs" when possible.
- Focus results using topic filtering. Try adding specific topics like "authentication" or "routing".
- Use pagination when you need more context — the API supports up to 10 pages per topic. Check the `hasNext` field in responses to know when more pages are available.
- Cache frequently used documentation locally for 6-24 hours to reduce API calls.

### Library Management

- Keep the `context7.json` file in your repositories up to date. Update it when adding new docs or changing structure.
- Exclude unnecessary folders, such as tests and build artifacts: `excludeFolders: ["test", "dist", "node_modules"]`.
- Add helpful rules for AI agents, such as "Always validate user input" or "Use TypeScript strict mode".
- Maintain version tags for important releases. For example, keep v1.x docs available even after releasing v2.x.

See [Library Owners](/adding-libraries) for configuration details.

## Need Help?

- **Troubleshooting**: [Common issues and solutions](/troubleshooting)
- **API Reference**: [Complete API documentation](/api)
- **MCP Details**: [Technical MCP server info](/mcp)
- **Community**: [Join our Discord](https://upstash.com/discord)