Ref MCP Server

Token-Efficient Documentation

Access 1000s of documentation sites using 60-95% fewer tokens than traditional tools. Smart session-aware filtering keeps your context clean and AI accurate.

Never Repeat Results

Session-aware de-duplication ensures you never see the same documentation twice. Refine your search naturally without context bloat.

Overview

Ref MCP Server gives your AI coding assistant instant access to up-to-date technical documentation for APIs, libraries, frameworks, and services - while using minimal tokens to keep your context window clean and your AI sharp. The Problem: Traditional documentation tools dump 10k-20k+ tokens of mostly irrelevant content into your context. This makes models measurably worse and wastes money on expensive API calls. The Solution: Ref intelligently searches documentation, filters results based on your session history, and returns only the ~500-5k most relevant tokens. The result? 60-95% fewer tokens, better AI responses, and faster development. Perfect for:

API integration and implementation
Library documentation lookup without leaving your AI assistant
Framework reference and best practices
Debugging with context from documentation
Third-party SDK integration
Private codebase documentation search
Technical decision-making research
Learning new technologies efficiently

Core capabilities:

Smart Search: Search 1000+ indexed documentation sites
Session Awareness: Never returns duplicate results in the same conversation
Intelligent Filtering: Returns ~5k relevant tokens from large pages (vs 20k+ with traditional fetch)
Public Documentation: APIs, libraries, frameworks, databases (free tier)
Private Documentation: GitHub repos, PDFs, internal wikis (Pro tier)
URL-to-Markdown: Convert any web page to clean markdown
Fallback Web Search: Find content not in indexed docs

Token Efficiency Example: Looking up a Figma API endpoint takes 439 tokens (54 search + 385 read) vs 10,000+ tokens with traditional tools. That’s 95% fewer tokens.

Why Ref vs Alternatives?

vs Context7 and Similar Tools

Traditional documentation tools approach:

Look up a library → automatically returns 10k most relevant tokens
2 libraries = 20k tokens dumped into context
No filtering or de-duplication
Full documentation dumps whether you need them or not

Ref’s intelligent approach:

Session-aware search → finds exact context needed
Returns ~500-5k tokens depending on query specificity
Smart de-duplication across searches prevents repetition
Progressive refinement without token waste
Average 60% fewer tokens, up to 95% reduction

Real Example: Figma API endpoint lookup = 54 tokens (search) + 385 tokens (read) = 439 totalTraditional tool = 10,000+ tokens automaticallySavings: 95%

vs Manual Web Scraping (fetch)

Problems with traditional fetch() / web scraping:

Large documentation pages = 20k+ tokens dumped into context
Mostly irrelevant content included (nav, footers, sidebars)
No de-duplication between searches
Context rot from excessive tokens
Models get measurably worse as context fills up

Ref’s advantages:

Pre-indexed documentation sites (instant search)
Smart relevance filtering based on your query
Session history prevents duplicate results
Clean markdown conversion
Returns only the ~5k most relevant tokens

Research shows: Models get measurably worse as you add more tokens. Ref keeps your context clean. Watch this video from Chroma on context rot.

Private Documentation Support

Unlike most documentation tools, Ref supports private documentation:Supported private sources:

Private GitHub repositories
Custom PDF documentation
Internal wiki pages
Proprietary codebases

Perfect for:

Enterprise internal tools documentation
Private SDK documentation
Custom framework references
Confidential API documentation
Company knowledge bases

Setup process:

Upgrade to Pro plan ($29/mo)
Email [email protected] with repository URLs or PDF files
Grant read access to specified repositories
Wait 24-48 hours for indexing
Search with natural language (Ref automatically searches private docs)

Private documentation is never shared and only accessible with your API key.

Session-Aware De-Duplication

How it works:Ref tracks every search and read in your conversation. When you refine your query or ask follow-up questions, Ref automatically filters out results you’ve already seen.Example workflow:

“How do I authenticate with the Stripe API?” → Returns authentication overview
“Show me code examples for payment intents” → Returns payment intent examples (NO repetition of auth info)
“What about error handling for declined payments?” → Returns error handling (NO repetition of previous results)

Benefits:

Progressive refinement without duplication
Cleaner context window
More room for relevant information
Better AI responses

This is automatic - you don’t need to manage it. Just ask follow-up questions naturally.

Quick Start

Get Your API Key

Unlimited searches (fair use)
Access to 1000s of public documentation sites
GitHub public repository search
Smart token-efficient retrieval
Session-aware de-duplication
URL-to-markdown conversion

After signing up:

Check your email and verify your account
Navigate to ref.tools/dashboard
Copy your API key from the dashboard

Free tier is perfect for individual developers. Paid tiers add private repository indexing and PDF documentation support.

Add to NimbleBrain Studio

In NimbleBrain Studio:

Navigate to MCP Servers in the sidebar
Click Add Server or Browse Registry
Search for “Ref” in the server registry
Click Add to Workspace
In the configuration dialog:
- Server Name: Ref
- Environment Variables:
  - Key: REF_API_KEY
  - Value: [Paste your API key]
Click Save & Enable

Ref uses streamable HTTP transport for optimal performance in Studio. No local server installation needed!

Test the Connection

Open a new playbook in Studio and try this prompt:“Search for documentation on how to authenticate with the Stripe API”You should see concise, relevant documentation with source links. Something like:

Authentication - Stripe API
URL: https://stripe.com/docs/api/authentication
Overview: Use personal access tokens or OAuth 2.0...

Follow-up prompt to test session awareness:“Show me code examples for creating a payment intent”You should see payment intent examples WITHOUT any repetition of the authentication info from your first search.

Notice how Ref never repeats results from your first search - it’s session-aware!

Supported Documentation

Ref indexes 1000+ documentation sites and public repositories, including:

Languages

Python
JavaScript/TypeScript
Go
Rust
Java
Ruby
PHP
C#/.NET
Swift
Kotlin
- many more

Frameworks

React/Next.js
Vue/Nuxt
Angular/Svelte
Django/Flask
FastAPI
Rails
Express/NestJS
Spring Boot
Laravel
ASP.NET Core

Cloud & APIs

AWS Services
Google Cloud
Azure
Stripe
Twilio
SendGrid
OpenAI
Anthropic
GitHub
Firebase/Supabase

Tools & Databases

Docker
Kubernetes
Terraform
PostgreSQL
MongoDB
Redis
Elasticsearch
Git
n8n
Figma API

Missing a documentation site? Email [email protected] with the URL and they’ll add it to the index. Most popular libraries are already included.

Available Tools

ref_search_documentation - Search Technical Documentation

Search for relevant documentation from 1000+ indexed sources including public APIs, libraries, frameworks, and private repositories.How it works:

Searches across indexed documentation sites and GitHub
Intelligently ranks results by relevance to your query
Filters out duplicate content from your session history
Returns concise summaries with source URLs
Uses minimal tokens (~54 tokens for a typical query)
Session-aware: never returns results you’ve already seen

Parameters:

Parameter	Type	Required	Description
`query`	string	Yes	Full sentence or question about documentation you need. Include programming language and framework/library names for best results.

Returns:

List of relevant documentation pages
Brief overview/excerpt of each result
URL for each result (use with ref_read_url to read full content)
Module ID for tracking
Filtered to remove results from previous searches in this session

Natural language examples:API Integration:

“How do I handle authentication in the Figma REST API?”
“What’s the endpoint for sending SMS with Twilio?”
“How do I create a Stripe payment intent?”

Library Documentation:

“React useEffect cleanup function best practices”
“Python asyncio error handling patterns”
“How do I use React Query for data fetching?”

Framework Guides:

“Next.js server-side rendering vs static generation”
“Django authentication with JWT tokens”
“FastAPI dependency injection examples”

Debugging:

“Solutions for ‘Cannot read property of undefined’ in React”
“Python asyncio event loop already running error”
“PostgreSQL connection pool exhausted”

Example Search Response:

    {
      "overview": "Authentication - Figma API. Use personal access tokens...",
      "url": "https://www.figma.com/developers/api#authentication",
      "moduleId": "figma-api-auth"
    }

Token Usage: A typical search uses ~54 tokens. Compare this to traditional tools that dump 10k+ tokens automatically.

Advanced Usage:Specific keywords: “Search for React hooks documentation, focusing on useEffect and useCallback”Version-specific: “What changed in Express.js version 5 from v4?”Private documentation (Pro tier): “Search my private company docs for authentication patterns” (Add ref_src=private to query for private docs)API endpoints: “Find the Twilio endpoint for sending SMS messages”Code examples: “Show me code examples for PostgreSQL connection pooling in Node.js”

Session Awareness: Ref tracks your search history. Refining your query won’t return duplicate results from previous searches - this keeps your context clean!

ref_read_url - Fetch and Convert Documentation

Fetch content from a URL and convert it to clean, readable markdown optimized for LLM consumption.How it works:

Fetches the web page content
Converts HTML to clean markdown
Uses session search history to filter irrelevant sections
Returns ~5k most relevant tokens from large pages
Prevents 20k+ token dumps that cause context rot
Preserves code blocks and formatting

Parameters:

Parameter	Type	Required	Description
`url`	string	Yes	Full URL of the documentation page to read. Should be a URL from `ref_search_documentation` results for best filtering.

Returns:

Markdown-formatted content
Intelligently filtered to most relevant sections (~5k tokens)
Preserves code blocks, syntax highlighting, and formatting
Includes page metadata
Clean, LLM-optimized output

Natural language examples:After searching: “Read the first result about Stripe authentication”With specific URL: “Read this Stripe API page: https://stripe.com/docs/api/payment_intents/create”For any web page: “Fetch and read this GitHub README: https://github.com/example/project”For blog posts: “Read this blog post about React performance optimization”Example Read Response:

    # Create a Payment Intent

    Creates a PaymentIntent object. After creating a PaymentIntent...

    ## Parameters
    - amount (required): Amount intended to be collected by this PaymentIntent
    - currency (required): Three-letter ISO currency code
    - payment_method_types (optional): Payment method types to use

    ## Code Example

    import stripe
    stripe.api_key = "sk_test_..."

    intent = stripe.PaymentIntent.create(
      amount=2000,
      currency="usd"
    )

    ## Returns
    Returns a PaymentIntent object if successful...

    [~5k tokens of relevant content, filtered based on your search context]

Without Ref: Standard web scraping can pull 20k+ tokens from large documentation pages, mostly irrelevant content (navigation, footers, sidebars).With Ref: Smart filtering returns ~5k most relevant tokens based on your search context. 60-80% token savings.

Best Practices:

Use with search results:
- First: Search for documentation
- Then: Read the most relevant result URL
- Benefit: Context-aware filtering gives you exactly what you need
Works on any URL:
- Documentation sites
- GitHub READMEs
- Blog posts
- Stack Overflow answers
- Tutorial sites
Progressive reading:
- Read one URL at a time
- Ask follow-up questions
- Read additional URLs as needed
- Session awareness prevents duplication

Token Efficiency: Reading a documentation page uses ~385-5,000 tokens (depending on page size and relevance filtering) vs 20,000+ tokens with standard fetch.

Example Workflow:

Search: “Stripe payment intent documentation” → Returns list of relevant pages (~54 tokens)
Read: Use ref_read_url on the most relevant result → Returns filtered markdown (~385 tokens)
Total: ~439 tokens for complete context → Traditional tool: 10,000+ tokens → Savings: 95%

Tool Selection Logic

You don’t need to choose tools manually!Ref’s AI agent automatically selects the right tool based on your natural language query:

“How do I…” / “What is…” / “Show me…” → ref_search_documentation
“Read this URL…” / “Fetch this page…” → ref_read_url
“Search for…” → ref_search_documentation

Just ask your question naturally and let Ref handle the rest.

Authentication & Configuration

API Key Required: This server requires a Ref API key for access to documentation search. Sign up at ref.tools/signup.

Getting Your API Key

Create Account

Visit ref.tools/signup and create an account with your email address.

Verify Email

Check your email and click the verification link. This is required to access the API.

Get API Key

Navigate to ref.tools/dashboard and copy your API key from the dashboard.

Add to Studio

In NimbleBrain Studio:

Go to Settings → MCP Servers → Ref
Add environment variable: REF_API_KEY = [your key]
Save changes

Free tier is unlimited searches (fair use) and includes all public documentation - perfect for most development needs.

Rate Limits & Pricing

Plan	Searches	Features	Price
Free	Unlimited*	Public docs, GitHub public repos, URL reading, session awareness	$0
Pro	Unlimited	+ Private GitHub repos, PDF docs, priority indexing	$29/mo
Team	Unlimited	+ Team sharing, admin controls, usage analytics	$99/mo
Enterprise	Unlimited	+ Custom indexing, SLA, dedicated support, on-premise	Custom

**Fair use applies to free tier. Contact [email protected] for high-volume needs. Token Usage (not API calls):

Average search: ~54 tokens
Average read: ~385-5,000 tokens (intelligently filtered)
No duplicate results in same session
60-95% more efficient than alternatives

Cost comparison (using Claude Opus API pricing): Traditional documentation tool:

Pulls 10k tokens per library lookup
2 libraries = 20k tokens = $0.30 per conversation
10 step conversation = $3.00 in documentation tokens

Ref:

Search + read = ~500-5k tokens per lookup
2 libraries = ~2k tokens = $0.03 per conversation
10 step conversation = $0.30 in documentation tokens

Savings: 90% on documentation token costs

While searches are unlimited, be mindful of token usage in your LLM context window. Ref optimizes for minimal token consumption.

Managing Your API Key in Studio

Your API key is securely stored in NimbleBrain Studio’s environment variables. To update your API key:

Go to Settings → MCP Servers
Find “Ref” in your server list
Click Edit Configuration
Update the REF_API_KEY environment variable
Click Save
Restart the server if needed (Studio usually does this automatically)

Studio uses Ref’s streamable HTTP transport for optimal performance - no local server installation or Docker required!

Private Documentation Setup

To index private GitHub repositories or PDF documentation:

Upgrade to Pro Plan

Private documentation indexing requires a Pro plan ($29/mo) or higher. Upgrade at ref.tools/dashboard.

Contact Ref Team

Email [email protected] with:

Your Ref account email
GitHub organization name (if applicable)
Repository URLs to index
PDF documentation files to upload (if any)
Internal wiki URLs (if crawlable)

Grant Access

For GitHub repositories:

Add Ref bot as a collaborator (they’ll provide the bot account)
Or provide a fine-grained personal access token with read access

For PDFs:

Upload files via the process Ref provides
Or email them directly (if not too large)

Wait for Indexing

Ref will notify you when indexing is complete:

Initial indexing: 24-48 hours
Incremental updates: Automatic
Re-indexing frequency: Configurable

Search Private Docs

Once indexed, search your private docs naturally:

“Search my private company docs for authentication patterns”
“Find documentation in our internal repos about payment processing”
Add ref_src=private to explicitly search only private docs
Or use “all” to search both public and private

Private documentation is only accessible with your API key and never shared with other users.

Security Best Practices

Protect Your API Key

Your Ref API key grants access to your documentation index and private repos:Do:

✅ Store key securely in Studio environment variables
✅ Never commit keys to version control
✅ Rotate keys periodically (every 90 days recommended)
✅ Use separate keys for different environments (dev/staging/prod)
✅ Monitor usage for unexpected activity in dashboard

Don’t:

❌ Share your API key publicly
❌ Hardcode keys in source code
❌ Use production keys in development
❌ Share keys between team members (use Team plan)

If your key is compromised, regenerate it immediately from your Ref dashboard. Old keys are instantly revoked.

Private Repository Security

When using private repository indexing:Access Control:

Only grant read access to necessary repositories
Use fine-grained personal access tokens (not full repo access)
Regularly audit indexed repositories in dashboard
Remove access when team members leave
Monitor search queries for sensitive data exposure

Data Privacy:

Ref only indexes repositories you explicitly authorize
Never stores repository credentials
Doesn’t re-share your private documentation
Complies with GitHub’s data usage policies
Can delete indexed data on request

Ref indexes content but never stores your GitHub credentials. Access tokens are used once for indexing and not retained.

Context Window Management

Even with token-efficient search, monitor your context usage:Best Practices:

Track total tokens in conversation (Studio shows this)
Clear context when switching to unrelated topics
Use specific queries to reduce reads needed
Let Ref’s de-duplication work (don’t start new conversations unnecessarily)
Monitor for context rot indicators (AI giving worse responses)

Signs of context overload:

AI responses become less relevant
AI starts ignoring instructions
Responses reference wrong information
Increased latency in responses

Solutions:

Start a new conversation
Use more specific queries
Read fewer URLs per conversation
Trust Ref’s filtering

Ref’s session tracking automatically prevents duplicate results, keeping your context cleaner than manual documentation lookup.

Example Workflows

API Integration
Library Research
Debugging Errors
Framework Migration
SDK Implementation
Private Codebase
Dependency Update
Architecture Decision
Security Audit
Performance Optimization
Learning New Tech

Scenario: Implement Stripe payment processing in your applicationStarting point: You need to integrate Stripe but haven’t used their API before.Step 1: Search for documentationPrompt: “How do I create a payment intent with the Stripe API?”What happens:

Searches Stripe documentation
Returns relevant API endpoints and overview
Includes authentication requirements
Shows brief code examples
~54 tokens used

Response:Authentication & Payment Intents - Stripe API URL: https://stripe.com/docs/api/payment_intents/create Overview: Creates a PaymentIntent object for collecting payment…Step 2: Read specific endpointPrompt: “Read the full documentation for creating payment intents”What happens:

Fetches Stripe API reference page
Converts to clean markdown
Filters to relevant sections (~385 tokens)
Preserves code examples in multiple languages
Ready to implement

Step 3: Handle edge casesPrompt: “Show me error handling for declined payments”What happens:

Searches for error handling (no repetition of Step 1/2 results!)
Returns error codes and handling strategies
Context-aware: focuses on what you haven’t seen yet

Result: Complete integration context in less than 500 tokens vs 10k+ with traditional toolsTotal tokens: ~600 (search + read + follow-up) Traditional tool: 15,000+ tokens Savings: 96%

Follow up with: “Show me webhook handling for payment confirmations” - Ref won’t repeat previous payment intent documentation!

Real-World Token Savings

Simple API Lookup

Task: Find Figma Comment API endpointTraditional: 10,000+ tokens (full API docs dump) With Ref: 439 tokens (54 search + 385 read)Savings: 95% fewer tokensCost impact:

Traditional: $0.15 (Claude Opus)
Ref: $0.007
Save $0.143 per lookup

Library Comparison

Task: Compare 2 state management librariesTraditional: 20,000+ tokens (2x full documentation) With Ref: 1,500 tokens (filtered key information)Savings: 92% fewer tokensCost impact:

Traditional: $0.30
Ref: $0.023
Save $0.277 per comparison

Migration Research

Task: Research framework migration (e.g., Vue 2 to Vue 3)Traditional: 30,000+ tokens (changelog + full migration guides) With Ref: 3,000 tokens (relevant sections only)Savings: 90% fewer tokensCost impact:

Traditional: $0.45
Ref: $0.045
Save $0.405 per migration

Debugging Session

Task: Research error and find solutionsTraditional: 15,000+ tokens (full Stack Overflow pages) With Ref: 2,000 tokens (answers only, no noise)Savings: 87% fewer tokensCost impact:

Traditional: $0.225
Ref: $0.03
Save $0.195 per debug session

Multi-step project impact: Let’s say you’re building a new feature that requires:

3 API integrations
2 library comparisons
1 debugging session
1 migration research

Traditional approach:

(3 × 10k) + (2 × 20k) + (1 × 15k) + (1 × 30k) = 115,000 tokens
Cost: $1.73 (Claude Opus)
Context: Severely degraded, multiple conversations needed

With Ref:

(3 × 500) + (2 × 1.5k) + (1 × 2k) + (1 × 3k) = 9,500 tokens
Cost: $0.143
Context: Clean, single conversation possible
Savings: 92% tokens, 92% cost, better AI responses

Why this matters: Large language models perform measurably worse as context windows fill up. Ref keeps your context clean and your AI assistant accurate, while saving significant API costs.

Troubleshooting

No Results Found

Error Message: “No results found” when searchingCommon causes:

Documentation site not yet indexed
- Ref indexes 1000+ sites but may not have yours yet
- Check supported documentation list
- Request indexing by emailing [email protected]
Query too specific or using wrong terminology
- Try broader search terms
- Use official library/framework names
- Include programming language in query
Very new or obscure library
- Recently released libraries may not be indexed yet
- Obscure/niche libraries may need manual indexing
Typo in library name
- Double-check spelling
- Try alternate names (e.g., “nodejs” vs “node.js”)

Solutions:

Try broader terms: “React hooks” instead of “React useEffect cleanup unmount”
Include framework: “Python asyncio” instead of just “async/await”
Use official names: “Vue.js” instead of “Vue3”
Request indexing: Email [email protected] with documentation URL
Use web search: Ref will automatically fall back to web search if needed

Most popular libraries and frameworks are already indexed. If you get no results for a major library, double-check your query wording.

Invalid API Key

Error Message: “Ref is not correctly configured” or “401 Unauthorized”Common causes:

API key not set in Studio
- Environment variable REF_API_KEY missing or empty
- Typo in environment variable name
Invalid or expired API key
- Key was regenerated in dashboard
- Key was revoked
- Copy/paste error (extra spaces, missing characters)
Email not verified
- Ref requires email verification before API access
- Check your email for verification link

Solutions:Step 1: Verify API key in Studio

Go to Settings → MCP Servers → Ref
Click Edit Configuration
Check that REF_API_KEY environment variable exists
Verify the key value (no quotes, no spaces)

Step 2: Regenerate key if needed

Log in to ref.tools/dashboard
Find API Keys section
Copy your current key OR regenerate new key
Update in Studio

Step 3: Verify email

Check your email for verification link from Ref
Click verification link
Wait 5 minutes for activation
Try again

Step 4: Test key

Try a simple search: “React documentation”
If it works, your key is valid

API keys are case-sensitive and should not include quotes or spaces. Copy directly from the Ref dashboard.

Incomplete Documentation

Issue: Results seem incomplete, truncated, or missing informationThis is by design! Ref intentionally filters content to:

Remove duplicate information from your session history
Filter irrelevant sections based on your query context
Keep token usage minimal (~5k max per read)
Prevent context rot from excessive tokens
Return only what’s needed for your specific question

Why this is actually good:

Better AI responses: Less noise = more accurate answers
Faster development: Get to relevant info immediately
Cost savings: 60-95% fewer tokens = lower API costs
Cleaner context: Your AI stays focused

Solutions if you need more:

Ask more specific follow-up questions
- “Show me error handling for this API”
- “What are the authentication options?”
- “How do I handle rate limits?”
Read additional URLs
- Search returns multiple results
- Read the next most relevant URL
- Each read is context-aware
Request the full page
- “Read the complete documentation for [specific topic]”
- Use ref_read_url directly on specific URL
- Accept higher token usage for completeness
Trust the filtering
- Ref’s AI knows what’s relevant
- You probably don’t need the omitted sections
- Follow-up questions fill in gaps as needed

If you genuinely need complete raw documentation, use ref_read_url on the specific page URL and ask for “complete” content. But consider whether you really need all 20k tokens or if 5k filtered tokens will suffice.

Private Docs Not Found

Error: Cannot find private repository documentationCommon causes:

Not on Pro plan
- Private documentation requires Pro ($29/mo) or higher
- Free tier only includes public documentation
Repository not indexed yet
- Indexing takes 24-48 hours after setup
- Check email for indexing confirmation
Repository access not granted
- Ref bot needs read access to repository
- Personal access token may have expired
Query not specifying private docs
- By default, Ref searches public docs only
- Need to include ref_src=private in query

Solutions:Step 1: Verify Pro plan

Log in to ref.tools/dashboard
Check your subscription status
Upgrade if needed

Step 2: Confirm indexing status

Check email for indexing completion notification
Or email [email protected] to check status
Wait full 24-48 hours before troubleshooting

Step 3: Verify repository access

Go to GitHub repository settings
Check that Ref bot has read access
Or verify personal access token is still valid

Step 4: Use correct query format

Include: “Search my private docs for [topic]”
Or add: ref_src=private to query
Or use: “Search all docs” to search both public and private

Initial setup checklist:

Pro plan active
Repository URL sent to [email protected]
Read access granted to Ref
Received indexing confirmation email
Waited 24-48 hours
Using ref_src=private in queries

Private repository indexing requires Pro plan and manual setup. Contact [email protected] to get started.

Repeated Results (Unexpected)

Issue: Getting the same results again despite session awarenessThis shouldn’t happen! Ref is specifically designed to never return repeated results in a session.If this occurs:Possible causes:

New conversation started
- Session tracking is per-conversation
- New conversation = fresh session
- This is expected behavior
Different query about same topic
- If query is significantly different, may return overlapping results
- This is rare but can happen
Server issue or bug
- Rare session tracking issue
- May need to report to Ref team

Solutions:If in same conversation:

Note the specific queries that caused repetition
Check if you accidentally started a new conversation
Try clearing conversation and testing again
Report to [email protected] with:
- Your query sequence
- Results that repeated
- Your Ref account email

If you want to see previous results again:

Start a new conversation (intentionally)
Or explicitly ask: “Show me that earlier result about X again”
Or use ref_read_url on the same URL again

Workaround if needed:

Phrase your follow-up questions more distinctly
Ask for “different approach” or “alternative methods”
Use ref_read_url for specific URLs

If you want to see previous results again for reference, start a new conversation or explicitly ask “show me that earlier result about X again”.

URL Fetch Fails

Error: “Cannot fetch URL” or timeout errorCommon causes:

URL not publicly accessible
- Behind login wall
- Requires authentication
- VPN or firewall protected
Site blocks automated access
- Bot protection (Cloudflare, etc.)
- Rate limiting
- User-agent filtering
URL doesn’t exist or moved
- 404 Not Found
- Redirect to different domain
- Site temporarily down
Network/connectivity issues
- Your internet connection
- Site’s servers down
- DNS issues

Solutions:Step 1: Verify URL in browser

Open the URL in your web browser
Can you access it without logging in?
Does it load successfully?

Step 2: Check URL format

Ensure URL is complete (includes https://)
No typos in URL
No special characters breaking the URL

Step 3: Try alternative approaches

Search for the topic instead of reading specific URL
Use public documentation alternative
Check if there’s a PDF version

Step 4: For private/authenticated content

Add to private documentation index (Pro plan)
Or manually copy content for private use
Or find public equivalent documentation

Unsupported URL types:

❌ Pages behind login walls
❌ Paywalled content (Medium, news sites)
❌ Captcha-protected sites
❌ Sites blocking bots/scrapers
❌ Local URLs (localhost, 192.168.x.x)
❌ Internal company URLs (intranet)

Ref cannot access content requiring authentication unless it’s part of your private indexed repositories (Pro plan).

Slow Response Time

Issue: Searches or reads taking longer than expectedTypical response times:

Simple search: less than 1 second
Document read: 1-2 seconds
Complex research: 2-3 seconds
Web fallback: 2-4 seconds

If experiencing slow responses:Common causes:

Ref API experiencing high load
- Peak usage times
- Temporary infrastructure issues
Your internet connection
- Slow or unstable connection
- High latency to Ref servers
Complex query requiring multiple sources
- Searching many documentation sites
- Large page requiring processing
Studio connection issues
- MCP server connection problems
- Studio performance issues

Solutions:Step 1: Check Ref status

Visit status.ref.tools (if available)
Check Ref Twitter/X for status updates
Or check #ref channel in NimbleBrain Discord

Step 2: Test your connection

Run speed test
Check latency to ref.tools
Try different network

Step 3: Simplify query

Start with simpler, more specific query
Break complex research into smaller questions
Search one library at a time

Step 4: Check Studio

Restart Studio if needed
Check Studio status page
Try disabling/re-enabling Ref server

Step 5: Contact support

If consistently slow (>10 seconds)
Email [email protected] with:
- Your location/region
- Example slow queries
- Your Ref account email

Even “slow” Ref searches (2-3 seconds) are faster than manually browsing documentation websites!

Server Connection Failed

Error: “Server connection timeout” or “Cannot connect to Ref”Common causes:

Studio server not enabled
- Ref server disabled in Studio settings
- Server configuration error
Network/firewall blocking
- Firewall blocking api.ref.tools
- Corporate proxy issues
- VPN interference
Ref API temporarily down
- Rare infrastructure issues
- Maintenance window
Invalid configuration
- Wrong URL in server config
- Missing required settings

Solutions:Step 1: Check Studio server status

Go to Settings → MCP Servers
Find “Ref” in server list
Check if enabled (toggle should be on)
Look for error indicators

Step 2: Restart server

In MCP Servers settings
Click “Ref” server
Click Disable, wait 5 seconds
Click Enable
Try your query again

Step 3: Verify configuration

Click Edit Configuration on Ref server
Check server URL: https://api.ref.tools/mcp
Verify REF_API_KEY environment variable exists
Save if you made changes

Step 4: Check network

Test connection to api.ref.tools in browser
Check firewall settings
Try different network (phone hotspot)
Disable VPN temporarily

Step 5: Clear Studio cache

Go to Studio Settings
Find Clear Cache or similar option
Restart Studio
Re-enable Ref server

Step 6: Contact support

Email [email protected]
Include error message
Include your OS and Studio version

Ref uses streamable HTTP transport. Studio manages all connection infrastructure automatically - no Docker or local servers needed.

Content Format Issues

Issue: Markdown formatting looks wrong, broken, or unreadableCommon causes:

Complex source formatting
- Some documentation sites have complex layouts
- Tables, diagrams, custom elements
- JavaScript-rendered content
Studio rendering issue
- Markdown renderer in Studio
- Special characters not escaped
Source site structure changed
- Documentation site was redesigned
- Ref parser needs updating

Expected behavior:

Clean markdown output
Preserved code blocks with syntax highlighting
Working links
Readable headers and lists
Tables formatted correctly

Solutions if formatting is broken:Step 1: Try the original URL

Visit the source URL in your browser
Compare with Ref’s output
Determine if issue is source or conversion

Step 2: Report persistent issues

Email [email protected] with:
- The URL with formatting issues
- Screenshot of problem
- Expected vs actual output
- Your Ref account email

Step 3: Use alternative source

Search for same information from different site
Use official documentation vs community tutorials
Try GitHub README instead of external docs

Step 4: Manual extraction (last resort)

Visit URL directly
Copy relevant content manually
Use AI to help extract key information

Known limitations:

Heavy JavaScript-rendered content may not convert well
Complex interactive documentation may lose functionality
Diagrams and images are not included (markdown only)
Some tables may render suboptimally

Ref continuously improves parsing for popular documentation sites. Reporting issues helps improve formatting for everyone.

Links & Resources

GitHub Repository

View source code, report issues, and contribute to development

Ref.tools Website

Official website, blog, and feature announcements

Sign Up

Create account and get your API key

Dashboard

Manage API keys, view usage, upgrade plan

Report Issues

Found a bug? Submit an issue on GitHub

Email Support

[email protected] - Get help, request indexing, report problems

GitHub

Browse repository code, issues, and pull requests

Tavily

AI-powered web search and research

Echo

Test and debug MCP server connections

Learning Resources

Token Efficiency Best Practices

Maximize Ref’s token savings:1. Use specific queries

✅ “React useEffect cleanup function”
✅ “Stripe payment intent error handling”
❌ “React hooks” (too broad)
❌ “Stripe documentation” (too vague)

2. Let sessions work for you

Don’t repeat similar questions
Build on previous searches with follow-ups
Trust the de-duplication
Avoid starting new conversations unnecessarily

3. Progressive refinement

Start with overview: “What is Zustand?”
Then specifics: “How do I use Zustand middleware?”
Then edge cases: “Zustand with TypeScript?”
Each query builds without repetition

4. Trust the filtering

Ref knows what’s relevant for your query
Don’t request “complete documentation”
Follow up with specific questions if needed
Remember: less tokens = better AI responses

5. Monitor context usage

Track total tokens in conversation (Studio shows this)
Start fresh conversation when context feels full
Watch for declining AI response quality
Clear context when switching topics

Anti-patterns to avoid:

❌ Starting new conversations unnecessarily
❌ Asking the same question multiple ways
❌ Requesting full documentation dumps
❌ Ignoring Ref’s smart filtering
❌ Over-reading URLs (read one at a time)

Optimization workflow:

Search with specific query → ~54 tokens
Read most relevant URL → ~385 tokens
Follow-up question → ~54 tokens (new search)
Read second URL if needed → ~385 tokens

Total: ~878 tokens for comprehensive understanding vs 20,000+ tokens with traditional approach Savings: 96%

Think of Ref as a research assistant that remembers everything you’ve already seen. Each follow-up builds on previous context without repetition.

Query Writing Tips

Write effective documentation queries:Good query structure:1. Be specific

Include library/framework name
Mention programming language
State your goal or use case
Include version if relevant

2. Use question format

“How do I…” → Implementation guidance
“What is…” → Concept explanation
“Show me…” → Code examples
“Compare…” → Feature comparison
“What’s the best way to…” → Best practices

3. Add context

Mention your environment (Node.js, browser, etc.)
Include relevant technologies (TypeScript, React, etc.)
State constraints (performance, security, etc.)

4. Focus on your goal

What are you trying to accomplish?
What problem are you solving?
What feature are you building?

Query examples by category:API Integration:

✅ “How do I authenticate with the Stripe API using API keys?”
✅ “What’s the endpoint for creating Twilio SMS messages?”
❌ “Stripe” (too vague)
❌ “API documentation” (not specific)

Library Usage:

✅ “How do I use React Query for data fetching?”
✅ “Python asyncio error handling best practices”
❌ “React Query” (no clear goal)
❌ “Python async” (too broad)

Framework Concepts:

✅ “Next.js server-side rendering vs static site generation”
✅ “Django authentication with JWT tokens”
❌ “Next.js features” (too broad)
❌ “Django security” (too vague)

Debugging:

✅ “Solutions for TypeError Cannot read property map of undefined in React”
✅ “How to fix Python asyncio event loop already running error”
❌ “Error in my code” (no context)
❌ “Help with bug” (not specific)

Performance:

✅ “React performance optimization for large lists”
✅ “PostgreSQL connection pooling best practices for Node.js”
❌ “Make app faster” (too vague)
❌ “Database optimization” (too broad)

Migration:

✅ “What changed in Express 5 from Express 4 breaking changes”
✅ “How to migrate Vue 2 filters to Vue 3”
❌ “New version” (no context)
❌ “Upgrade help” (not specific)

Ref understands natural language - write queries like you’re asking a knowledgeable colleague, not a search engine.

Session Management

Understanding session-aware search:How sessions work:

Session creation
- Each new conversation creates a session
- Session tracks all your searches and reads
- Persists for the entire conversation
- Automatically cleared when you start new conversation
De-duplication
- Ref remembers every search result returned
- Filters out results you’ve already seen
- Allows query refinement without repetition
- Keeps context clean and focused
Progressive refinement
- Each search builds on previous ones
- Follow-up questions get new information only
- No manual management needed
- Automatic and transparent

Example session:

“Python async/await syntax” → Returns basic intro to async/await
“Python async error handling” → Returns error handling (NO repeat of basics)
“Python async performance best practices” → Returns performance tips (NO repeat of previous results)
“How do I use asyncio.gather?” → Returns gather() documentation (NO repeat of anything)

Each query gets ~5k new tokens, total ~20k for comprehensive understanding vs 50k+ tokens with traditional approach (with massive duplication)When to start a fresh session:Good reasons:

Completely different topic/library
Want to see previous results again
Context window getting full
AI responses degrading in quality
Switching projects or tasks

Bad reasons:

❌ Think you’ll get better results (won’t)
❌ Want to “reset” search quality (unnecessary)
❌ Afraid of context bloat (Ref prevents this)
❌ Just finished one query (use same session!)

Session benefits:

Cleaner context: No repeated information
Better AI: More room for relevant content
Faster research: Ask follow-ups without waste
Cost savings: 60-95% fewer tokens
Natural flow: Works like human conversation

Session tracking is automatic - you don’t manage it manually!

Session tracking is one of Ref’s killer features. It’s why you can ask 5-10 related questions without context overload.

Private Documentation Setup

Setting up private repository indexing:Requirements:

Pro plan or higher ($29/mo)
GitHub repositories (public or private)
Or PDF documentation files
Read access to repositories

Setup process:Step 1: Upgrade to Pro

Log in to ref.tools/dashboard
Click Upgrade or Billing
Choose Pro plan ($29/mo)
Enter payment information
Confirm upgrade

Step 2: Submit indexing request Email [email protected] with:Subject: Private Documentation Indexing RequestRef Account Email: [email protected]GitHub Repositories to Index:

PDF Documentation:

[Attach PDFs or provide download links]

Internal Wiki (if applicable):

https://wiki.yourcompany.com
[Provide access credentials if needed]

Notes:

Any special instructions or requirements
Preferred re-indexing frequency
Specific branches to index (default: main/master)

Step 3: Grant repository accessOption A: Add Ref bot as collaborator

Go to repository Settings → Collaborators
Add Ref bot account (they’ll provide username)
Grant Read access only

Option B: Fine-grained personal access token

Go to GitHub Settings → Developer settings → Personal access tokens → Fine-grained tokens
Create new token
Set repository access to only needed repos
Grant “Contents: Read-only” permission
Send token to [email protected] (securely)

Step 4: Wait for indexing

Initial indexing: 24-48 hours
Email confirmation when complete
Incremental updates: Automatic (usually daily)
Re-indexing on significant changes

Step 5: Search your private docsIn Studio, try:

“Search my private docs for authentication patterns”
“Find documentation in our internal repos about API gateway”
Include ref_src=private in query to search only private docs
Or use ref_src=all to search both public and private

Best practices:Documentation organization:

Use clear README.md files in each repo
Organize docs/ folders with logical structure
Use meaningful file names
Include code examples in documentation
Keep documentation up to date

Access control:

Index only necessary repositories
Use fine-grained tokens (not full repo access)
Regularly audit indexed repositories
Remove access when team members leave
Monitor search queries for sensitive data

Maintenance:

Update documentation regularly
Notify Ref of major doc restructures
Request re-indexing after big changes
Use conventional commit messages
Keep important docs in main/master branch

Private documentation is never shared with other users and is only accessible with your API key. Ref complies with GitHub’s data usage policies.

Supported Documentation Types

What Ref can index and search:Public sources (Free tier):Official documentation sites:

Framework docs (React, Vue, Angular, Django, etc.)
Language references (Python, JavaScript, Go, Rust, etc.)
Library documentation (npm, PyPI, crates.io, etc.)
API references (Stripe, Twilio, AWS, GCP, etc.)
Database documentation (PostgreSQL, MongoDB, Redis, etc.)
Tool guides (Docker, Kubernetes, Terraform, etc.)

GitHub public repositories:

README.md files
docs/ folders
Wiki pages
Code examples
Issue discussions (limited)

Community resources:

Tutorial sites
Blog posts
Stack Overflow (via web search fallback)
Community forums
Technical articles

Private sources (Pro+ tier):Private GitHub repositories:

Company internal libraries
Proprietary frameworks
Internal API documentation
Custom tool guides
Architecture documentation
Code example repositories

PDF documentation:

API specifications
Technical manuals
Internal wiki exports
Product documentation
Design system guides
Architecture diagrams with text

Internal wikis (if crawlable):

Confluence pages
Notion docs
GitHub wikis (private)
Custom internal wikis

NOT supported:Authentication-required:

❌ Content behind login walls
❌ Paywalled documentation sites
❌ SSO-protected wikis (unless added as private docs)

Dynamic/Interactive:

❌ Sites requiring JavaScript to render
❌ Interactive documentation playgrounds
❌ Content generated client-side
❌ Captcha-protected sites

Media:

❌ Video content (YouTube, courses)
❌ Audio podcasts
❌ Images without text
❌ Diagrams without descriptions

Restricted:

❌ Sites blocking automated access
❌ Rate-limited APIs without key
❌ Geofenced content
❌ Content violating ToS to scrape

Request new documentation:If Ref doesn’t have a documentation site you need:

Email [email protected]
Include: Full URL to documentation site
Briefly explain why it’s useful
Most requests added within 1 week

Popular sites already indexed:

✅ 1000+ documentation sites
✅ All major frameworks and languages
✅ Top 100 npm packages
✅ Top 50 PyPI packages
✅ Major cloud providers (AWS, GCP, Azure)
✅ Popular APIs (Stripe, Twilio, SendGrid, etc.)

If you’re not sure if a site is indexed, just search for it! Ref will automatically fall back to web search if needed.

Integration with Other Tools

Using Ref with other MCP servers:Ref works beautifully alongside other MCP servers for powerful workflows:Ref + GitHub ServerPerfect combination:

Ref: Search API documentation
GitHub: Read actual code from repositories
Workflow: Understand API → See implementation examples

Example:

Ref: “How do I authenticate with GitHub API?” → Returns authentication documentation
GitHub: “Show me authentication code in example-repo” → Returns real implementation
Implement with both docs and code examples

Ref + TavilyComplementary capabilities:

Ref: Technical documentation and API references
Tavily: General web search and research
Workflow: Technical specs → Broader context

Example:

Ref: “Stripe payment intent API documentation” → Returns official API reference
Tavily: “Stripe payment intent best practices 2025” → Returns blog posts, tutorials, discussions
Combine official docs with community wisdom

Ref + PostgreSQL ServerDatabase development:

Ref: PostgreSQL documentation
PostgreSQL: Execute queries and analyze
Workflow: Learn syntax → Test queries

Example:

Ref: “PostgreSQL JSON functions documentation” → Returns JSONB operators and functions
PostgreSQL: Execute test queries with JSONB → See real results and performance
Optimize based on docs and actual performance

Ref + Any Code Execution ServerLearn and test:

Ref: Get documentation and examples
Code Server: Test code immediately
Workflow: Read docs → Write code → Test → Refine

Multi-server workflow example:Goal: Implement Stripe payments with PostgreSQL storage

Ref: “Stripe payment intent creation”
Ref: “PostgreSQL transaction best practices”
Code: Write payment processing function
PostgreSQL: Test database schema and queries
Ref: “Stripe webhook handling”
Code: Implement webhook endpoint
Test end-to-end

Benefits of multiple MCP servers:

Specialized capabilities: Each server does one thing well
Complementary features: Tools work together naturally
Flexible workflows: Combine as needed for your task
Context sharing: AI maintains context across servers
Single conversation: No switching between interfaces

NimbleBrain Studio allows multiple MCP servers simultaneously. Enable all the servers you need and use them together seamlessly.

Need help? Join the NimbleBrain Discord or email [email protected]Ref support: Email [email protected] for Ref-specific questions, indexing requests, or private documentation setup

Email Support

Get Started

Core Features

Developer Tools

Token-Efficient Documentation

Never Repeat Results

Overview

Why Ref vs Alternatives?

Quick Start

Supported Documentation

Languages

Frameworks

Cloud & APIs

Tools & Databases

Available Tools

Tool Selection Logic

Authentication & Configuration

Getting Your API Key

Rate Limits & Pricing

Managing Your API Key in Studio

Private Documentation Setup

Security Best Practices

Example Workflows

Real-World Token Savings

Simple API Lookup

Library Comparison

Migration Research

Debugging Session

Troubleshooting

Links & Resources

GitHub Repository

Ref.tools Website

Sign Up

Dashboard

Report Issues

GitHub

Tavily

Echo

Learning Resources

Get Started

Core Features

Developer Tools

Token-Efficient Documentation

Never Repeat Results

​Overview

​Why Ref vs Alternatives?

​Quick Start

​Supported Documentation

Languages

Frameworks

Cloud & APIs

Tools & Databases

​Available Tools

​Tool Selection Logic

​Authentication & Configuration

​Getting Your API Key

​Rate Limits & Pricing

​Managing Your API Key in Studio

​Private Documentation Setup

​Security Best Practices

​Example Workflows

​Real-World Token Savings

Simple API Lookup

Library Comparison

Migration Research

Debugging Session

​Troubleshooting

​Links & Resources

GitHub Repository

Ref.tools Website

Sign Up

Dashboard

Report Issues

Email Support

​Related MCP Servers

GitHub

Tavily

Echo

​Learning Resources

Overview

Why Ref vs Alternatives?

Quick Start

Supported Documentation

Available Tools

Tool Selection Logic

Authentication & Configuration

Getting Your API Key

Rate Limits & Pricing

Managing Your API Key in Studio

Private Documentation Setup

Security Best Practices

Example Workflows

Real-World Token Savings

Troubleshooting

Links & Resources

Related MCP Servers

Learning Resources