Building and Pricing a Commercial MCP Server for Documentation Search

pulsemcp · Tech · 2025 · source Agentic: yes · promotional bias: med · source-backed · extracted with prompt 0.5.4 (schema v2)

Generated from extraction.json — do not edit by hand. Every claim cites verbatim source evidence; stated means the quote directly asserts the claim, implied means it supports it indirectly.

Problem

Domain: Commercial MCP documentation search

Ref needed to price a standalone paid MCP server for coding-agent documentation search in a market where most MCP servers were free, while covering search, LLM, crawling, and indexing costs.

Constraints:

MCP users expect free or bundled servers.
Individual developers may run tens of searches while agents may run thousands.
Search volume creates variable costs, while indexing and crawling create fixed costs.
Users only perceive value when they search, not when indexes are maintained.

Architecture

Ref packaged documentation search as a paid MCP server with two credit-billed tools, ref_search_documentation and ref_read_url. New users receive 200 non-expiring free credits, paid users buy $9/month for 1,000 credits, and each tool call consumes one credit, aligning user-visible search value with variable and fixed operating costs.

Diagram confidence: explicit (topology described by the source).

flowchart LR
  coding-agent[Coding Agent] --> ref-mcp-server[Ref MCP Server]
  ref-mcp-server --> search-tool[Search Tool]
  ref-mcp-server --> read-url-tool[Read URL Tool]
  search-tool --> credit-system[Credit System]
  read-url-tool --> credit-system[Credit System]
  credit-system --> subscription-billing[Subscription Billing]
  search-tool --> search-infrastructure[Search Infrastructure]
  search-infrastructure --> ai-processing[AI Processing]
  read-url-tool --> web-crawler[Web Crawler]
  web-crawler --> search-infrastructure[Search Infrastructure]

Drag to pan · scroll or use +/− to zoom · reconstructed from the source's described component topology

Components

Component	Role	Interacts with
`Coding Agent`	Uses MCP tools to search and read documentation.	`Ref MCP Server`
`Ref MCP Server`	Commercial MCP server exposing documentation search and URL read tools.	`Search Tool`, `Read URL Tool`, `Credit System`
`Search Tool`	Searches documentation and consumes one credit.	`Credit System`, `Search Infrastructure`
`Read URL Tool`	Reads a URL and consumes one credit.	`Credit System`, `Web Crawler`
`Credit System`	Tracks free and paid usage credits.	`Ref MCP Server`, `Subscription Billing`
`Search Infrastructure`	Turbopuffer-backed search indices and query volume layer.	`Search Tool`, `AI Processing`
`AI Processing`	LLM processing in the retrieval pipeline.	`Search Infrastructure`
`Web Crawler`	Keeps documentation current and drives fixed operating cost.	`Read URL Tool`, `Search Infrastructure`
`Subscription Billing`	Charges monthly minimums and additional credit blocks.	`Credit System`

Data flow

An AI coding agent calls Ref's MCP tools, each call consumes one credit, search infrastructure queries Turbopuffer indices, AI processing ranks or interprets results, and crawling/indexing keeps public and private documentation fresh while subscription credits fund fixed costs.

“Our MCP server has two tools, (ref_search_documentation and ref_read_url), each billed at 1 credit per call.”article, stated

“Search infrastructure - Turbopuffer hosts our search indices, charging for both data storage and query volume.”article, stated

Why this architecture

Ref chose usage credits because the product serves both humans and autonomous agents, and users perceive value through searches rather than indexing. A monthly minimum covers fixed index/crawl costs, while additional credits let high-volume agents scale usage.

“Users only pay for searches, not indexing, and the monthly minimum covers our fixed costs while scaling with actual usage.”article, stated

“An MCP server can serve individual humans making occasional requests or autonomous agents making thousands of calls.”article, stated

Models used: MCP · Turbopuffer · LLMs

Scale

New users receive 200 free credits that never expire.
“New users get 200 free credits that never expire to try the product. We estimated 200 searches represent approximately 10 weeks of casual usage for a normal developer in Cursor or Claude Code, so this felt generous.”article, stated
Paid users get 1,000 credits for $9/month, or $0.009 per search.
“To upgrade, users pay $9 per month for 1,000 credits and can buy additional blocks of 1,000 credits for $9 each.”article, stated
Ref estimates 200 searches as about 10 weeks of casual usage.
“We estimated 200 searches represent approximately 10 weeks of casual usage for a normal developer in Cursor or Claude Code”article, stated
After three months, Ref reports thousands of weekly users and hundreds of subscribers.
“Since launching with this pricing and packaging 3 months ago, Ref has thousands of weekly users and hundreds of subscribers”article, stated

Alternatives considered (roads not taken)

Charge for each repository or PDF indexed.

Rejected because: Users perceive value when they search, not when indexing work is done.

“It’s tempting to focus only on pricing to match the underlying cost because then you’re certain that each operation you do on behalf of the user is profitable. For us, that would mean billing for each repo and PDF a user indexes in Ref.”article, stated

Two-week free trial.

Rejected because: Usage varies too widely between occasional developers and high-volume agent developers.

“A straightforward two-week free trial wouldn't match our wide range of usage patterns. A single developer might not search much in two weeks and reach the end unsure about upgrading. An agent developer might make thousands of queries in two weeks at significant cost to us.”article, stated

Free public index with paid private indexes.

Rejected because: Ref chose premium positioning and full-featured free evaluation instead.

“Ref could have provided our public index for free and charged for private indexes, but we chose a different path.”article, stated

Patterns

`rag-retrieval` (documentation search)

Ref provides premium documentation search for coding agents through MCP tools.

“premium documentation search specifically for coding agents.”article, stated

`tool-use-orchestration` (MCP)

Ref exposes search and URL-reading as MCP tools billed per call.

“Our MCP server has two tools, (ref_search_documentation and ref_read_url), each billed at 1 credit per call.”article, stated

`cost-aware-routing` (pricing)

Credit pricing maps user value to search calls while covering fixed crawling/indexing costs.

“The monthly commitment covers our ongoing indexing costs while additional credit purchases allow usage to scale”article, stated

`batch-offline-processing` (index maintenance)

The business model accounts for ongoing web crawling and index maintenance as fixed infrastructure cost.

“Web crawling - Our highest expense: compute resources for running the web crawler that keeps documentation current.”article, stated

Tradeoffs

Pricing unit

Chose Credits per search/read call over Billing for indexing repositories or PDFs.

Rationale: Search is the value event users understand, while monthly minimums cover fixed costs.

“Users only pay for the value they receive (searches), but we still cover our fixed costs.”article, stated

Free trial design

Chose 200 non-expiring usage credits over Time-limited trial.

Rationale: Usage-based trials fit both occasional humans and high-volume agent developers better than calendar windows.

“Our constraints became clear: offer Ref for free with every feature available, but limit the trial based on usage, not time.”article, stated

Market position

Chose Paid premium MCP server over Free public-index commodity server.

Rationale: Ref differentiated on search precision and private indexes, not free access.

“Ref sits between Context7 and Tavily/Exa, offering premium documentation search specifically for coding agents.”article, stated

Gotchas (what bit them)

MCP monetization fights a free ecosystem.

Root cause: Most MCP servers are free or bundled into existing products.

Resolution: Position Ref as premium, offer full-featured free credits, and communicate search precision/private indexes.

“The free ecosystem challenge: MCP is new and nearly everything else is free.”article, stated

Usage patterns vary from humans to autonomous agents.

Root cause: A developer may search tens of times, while agents can make thousands of calls.

Resolution: Use credits that support both casual free use and high-volume paid blocks.

“supports both individuals doing tens of queries a day and teams or agents doing thousands.”article, stated

Charging only for searches must still fund indexing.

Root cause: Crawling and index maintenance are fixed costs that users do not directly value per operation.

Resolution: Use a monthly minimum subscription to cover ongoing fixed costs.

“charge only based on search volume while still covering our ongoing indexing costs.”article, stated

Evaluation

Ref evaluates pricing through cost-structure modeling, competitor benchmarks, user usage ranges, free-credit conversion, weekly usage, and subscriber adoption.

Metrics: Credits per call · Weekly users · Subscribers · Search cost · Fixed indexing cost · Free-credit usage

“Understanding our cost structure was essential for building a sustainable pricing model.”article, stated

“Since launching with this pricing and packaging 3 months ago, Ref has thousands of weekly users and hundreds of subscribers”article, stated

Outcomes

Ref launched a paid MCP documentation search server.
The credit model offers 200 free non-expiring credits and $9/month for 1,000 credits.
The article reports thousands of weekly users and hundreds of subscribers after three months.

The pricing is $0.009 per search/read call, with 200 free credits, 1,000 monthly credits for $9, and reported thousands of weekly users plus hundreds of subscribers.

“This works out to $0.009 per search, aligning with other search services like Exa and Tavily.”article, stated