> ## Documentation Index
> Fetch the complete documentation index at: https://ulpi.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# FAQ

> Frequently asked questions and troubleshooting

## Getting Started

<AccordionGroup>
  <Accordion title="Do I need to install anything?">
    You need:

    * An AI assistant that supports MCP (Claude Desktop or VSCode with Continue extension)
    * A ULPI.io account
    * An API key

    No other software installation required. ULPI runs in the cloud.
  </Accordion>

  <Accordion title="Is there a free tier?">
    Yes! The free tier includes:

    * Up to 3 API keys
    * 100 searches per day
    * 1 GB of indexed documentation
    * All core MCP features

    Perfect for personal projects and trying out ULPI.
  </Accordion>

  <Accordion title="Which AI assistants work with ULPI?">
    **Fully Supported:**

    * Claude Desktop (built-in MCP support)
    * VSCode with Continue extension
    * VSCode with Codeium (Pro plan)

    **Coming Soon:**

    * GitHub Copilot Chat (when MCP support launches)
    * Cursor IDE
    * JetBrains IDEs
  </Accordion>

  <Accordion title="Can I index private repositories?">
    Yes! ULPI supports private GitHub repositories. During setup:

    1. Authorize ULPI to access your repos
    2. Select which repositories to index
    3. Only you (your tenant) can search them

    Your data is completely isolated from other users.
  </Accordion>
</AccordionGroup>

## Authentication & Security

<AccordionGroup>
  <Accordion title="How secure are my API keys?">
    API keys in ULPI:

    * Are hashed and encrypted at rest
    * Only shown once during creation
    * Can be revoked instantly
    * Support expiration dates
    * Track usage for auditing

    Always store keys securely (never commit to Git).
  </Accordion>

  <Accordion title="Can other tenants see my documentation?">
    **No.** ULPI enforces strict tenant isolation:

    * Each tenant has a separate Typesense collection
    * API keys are scoped to one tenant only
    * Database queries automatically filter by tenant ID
    * No cross-tenant access is possible

    See [Security](/security) for technical details.
  </Accordion>

  <Accordion title="What happens if my API key is compromised?">
    If you suspect a compromised key:

    1. **Immediately revoke it** in the ULPI dashboard
    2. **Create a new key** with a different name
    3. **Update your MCP configuration** with the new key
    4. **Review usage logs** to check for suspicious activity

    Revocation is instant - the old key stops working immediately.
  </Accordion>

  <Accordion title="Should I use test or live keys?">
    **Test keys** for:

    * Local development
    * Experimenting with ULPI
    * CI/CD pipelines

    **Live keys** for:

    * Production use
    * Shared team environments
    * Customer-facing integrations

    Test keys don't count toward billing.
  </Accordion>
</AccordionGroup>

## Using MCP Tools

<AccordionGroup>
  <Accordion title="Why aren't my searches returning results?">
    **Common causes:**

    1. **Indexing not complete**
       * Check ULPI dashboard for indexing status
       * Large repos can take 5-10 minutes

    2. **No documentation files found**
       * ULPI indexes .md, .mdx, and .txt files
       * Check if your repo contains these file types

    3. **Query too specific**
       * Try broader search terms
       * Remove repository/branch filters

    4. **Wrong tenant/API key**
       * Verify you're using the correct key
       * Check key is associated with right tenant
  </Accordion>

  <Accordion title="How do I search a specific repository?">
    Ask your AI assistant to filter by repository:

    ```
    "Search the api-docs repository for webhooks"
    ```

    or get the repository ID first:

    ```
    "List my repositories"
    "Search repository ID 5 for authentication"
    ```

    See [MCP Tools](/mcp/tools) for more filtering options.
  </Accordion>

  <Accordion title="Can I search multiple repositories at once?">
    Yes! By default, `search_documentation` searches **all** your repositories.

    To search specific repos, ask your AI to search each one:

    ```
    "Search these repositories for error handling:
    - api-docs
    - backend-wiki
    - frontend-guides"
    ```
  </Accordion>

  <Accordion title="What's the difference between snippet and standard search?">
    **Snippet (quick search):**

    * Returns 30% of each document
    * Up to 20 results
    * Faster, uses fewer tokens
    * Great for browsing

    **Standard (default):**

    * Returns full document content
    * Up to 10 results
    * More detailed answers
    * Best for most queries

    **Comprehensive:**

    * Full content, 30 results
    * For deep research
    * Uses more tokens

    See [MCP Tools - Detail Levels](/mcp/tools#detail-levels)
  </Accordion>
</AccordionGroup>

## Technical Issues

<AccordionGroup>
  <Accordion title="Claude Desktop doesn't see ULPI tools">
    **Checklist:**

    1. ✅ Configuration file exists at correct location
    2. ✅ JSON syntax is valid (check at [jsonlint.com](https://jsonlint.com))
    3. ✅ API key is correct (no extra spaces)
    4. ✅ Claude Desktop was fully restarted (not just window closed)

    **Still not working?**

    * Delete and recreate the config file
    * Reinstall Claude Desktop
    * Try a different API key

    See [Claude Desktop Setup](/mcp/claude-desktop#troubleshooting)
  </Accordion>

  <Accordion title="Getting 'Invalid API Token' errors">
    **Possible causes:**

    1. **Key copied incorrectly**
       * Check for extra spaces or line breaks
       * Copy directly from ULPI dashboard

    2. **Key was revoked**
       * Check key status in dashboard
       * Create a new key if revoked

    3. **Key expired**
       * Check expiration date
       * Renew or create new key

    4. **Wrong environment**
       * Test keys only work in test environment
       * Live keys only work in live environment
  </Accordion>

  <Accordion title="Searches are timing out">
    **Solutions:**

    1. **Increase timeout** in your MCP config:

    ```json theme={null}
    {
      "mcpServers": {
        "ulpi": {
          "url": "https://api.ulpi.io/mcp/documentation",
          "timeout": 30000,
          // ...
        }
      }
    }
    ```

    2. **Use snippet detail level** for faster searches:

    ```
    "Give me a quick snippet search for authentication"
    ```

    3. **Check ULPI status** at [status.ulpi.io](https://status.ulpi.io)

    4. **Contact support** if issue persists
  </Accordion>

  <Accordion title="Configuration file location on my OS?">
    **Claude Desktop:**

    * **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
    * **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
    * **Linux**: `~/.config/Claude/claude_desktop_config.json`

    **VSCode (Continue):**

    * **All OS**: Use Command Palette → "Continue: Open config.json"

    **VSCode (Settings):**

    * **All OS**: Use Command Palette → "Preferences: Open Settings (JSON)"
  </Accordion>
</AccordionGroup>

## Billing & Plans

<AccordionGroup>
  <Accordion title="How is usage calculated?">
    Usage is measured by:

    * **Searches**: Each `search_documentation` call
    * **Expands**: Each `expand_document` call
    * **Storage**: Total size of indexed documentation

    **Not counted:**

    * `list_repositories` calls
    * Failed requests
    * Test environment usage
  </Accordion>

  <Accordion title="What happens if I exceed my plan limits?">
    **Free tier:**

    * Searches stop at 100/day
    * Resets at midnight UTC
    * Upgrade to continue

    **Pro tier:**

    * Soft limit warnings at 80%
    * Hard limit at 10,000/day
    * Auto-upgrades to Enterprise if exceeded 3 times

    **Enterprise:**

    * Custom limits
    * No automatic cutoffs
  </Accordion>

  <Accordion title="Can I upgrade or downgrade?">
    Yes! Change plans anytime:

    * **Upgrades** take effect immediately
    * **Downgrades** take effect next billing cycle
    * No data is lost when changing plans

    Go to [app.ulpi.io/billing](https://app.ulpi.io/billing)
  </Accordion>

  <Accordion title="Do you offer student/education discounts?">
    Yes! Students, educators, and open-source projects get:

    * 50% off Pro plan
    * Extended free tier (300 searches/day)

    Apply at [ulpi.io/education](https://ulpi.io/education) with:

    * .edu email address
    * Or student ID verification
    * Or link to open-source project
  </Accordion>
</AccordionGroup>

## Repository Management

<AccordionGroup>
  <Accordion title="How often are my docs re-indexed?">
    ULPI automatically re-indexes when:

    * You push to GitHub (via webhooks)
    * Every 24 hours as a backup
    * Manually triggered from dashboard

    Typical re-index time: 1-5 minutes per repository.
  </Accordion>

  <Accordion title="Can I index documentation from other sources?">
    **Currently supported:**

    * GitHub repositories
    * GitLab repositories (coming soon)
    * Direct file uploads (coming soon)

    **Not yet supported:**

    * Confluence
    * Notion
    * Google Docs

    Vote for integrations at [feedback.ulpi.io](https://feedback.ulpi.io)
  </Accordion>

  <Accordion title="Which file types are indexed?">
    ULPI indexes:

    * Markdown (.md, .mdx)
    * Plain text (.txt)
    * ReStructuredText (.rst)
    * AsciiDoc (.adoc)

    Coming soon:

    * HTML (.html)
    * PDF (.pdf)
    * Microsoft Word (.docx)
  </Accordion>

  <Accordion title="Can I exclude certain files or folders?">
    Yes! Add a `.ulpiignore` file to your repository root:

    ```
    # Ignore build output
    /dist
    /build

    # Ignore examples
    /examples/*.md

    # Ignore drafts
    **/*draft*.md
    ```

    Uses .gitignore syntax.
  </Accordion>
</AccordionGroup>

## Still Need Help?

<CardGroup cols={2}>
  <Card title="Email Support" icon="envelope" href="mailto:support@ulpi.io">
    [support@ulpi.io](mailto:support@ulpi.io) - We respond within 24 hours
  </Card>

  <Card title="Community Discord" icon="discord" href="https://discord.gg/ulpi">
    Join our community for real-time help
  </Card>

  <Card title="Status Page" icon="signal" href="https://status.ulpi.io">
    Check for service outages
  </Card>

  <Card title="Changelog" icon="clock-rotate-left" href="https://ulpi.io/changelog">
    See what's new in ULPI
  </Card>
</CardGroup>