Skip to main content
Glama
natural-docs-mcp

natural-docs-mcp

by jsharma103

natural-docs-mcp

Search, read, and look up Natural API documentation from your AI agent.

Unofficial. Not affiliated with, endorsed by, or operated by Natural AI, Inc. A community companion to Natural's official operational MCP. It reads Natural's own published docs — it moves no money and needs no credentials.

Live endpoint: https://natural-docs-mcp.jsharma103.workers.dev/mcp


Why

Natural's official MCP server exposes 24 operational tools (payments, wallets, agents, transfers) but no way to read the docs. An agent mid-integration ends up fetching raw llms.txt over HTTP — which fails on hosts without web access, burns context on full-page dumps, and offers no ranked search.

This server adds the missing documentation surface: four read-only tools, one hosted URL, nothing to install. Docs are fetched live from docs.natural.com (cached 15 min), so answers are never stale and no snapshot is redistributed.

Related MCP server: docs

Tools

Tool

Answers

Notes

list_docs

"What docs exist?"

Sections → pages, a table of contents (~2KB)

search_docs

"Which page covers X?"

BM25 ranking, returns snippets not full pages

read_doc

"Give me that page."

Fetches a page as markdown by slug or URL

lookup_endpoint

"Exact shape of this endpoint?"

OpenAPI lookup; detail=true returns pruned parameter/request/response schemas

Install

No install, no auth — add one URL as a custom MCP server.

Claude Code

claude mcp add --transport http natural-docs https://natural-docs-mcp.jsharma103.workers.dev/mcp --scope user

Then /mcp to confirm natural-docs is connected. Try: "Search the Natural docs for idempotency."

Claude (claude.ai / Desktop)

Sidebar → Customize → Connectors → Add custom connector. Name Natural Docs, URL https://natural-docs-mcp.jsharma103.workers.dev/mcp.

Cursor

Settings → Tools & MCPs → New MCP Server, then merge:

{
  "mcpServers": {
    "natural-docs": { "url": "https://natural-docs-mcp.jsharma103.workers.dev/mcp" }
  }
}

How it works

Three published, machine-readable sources are fetched at runtime and cached in-isolate:

  • docs.natural.com/llms.txt — the section/page index (list_docs)

  • docs.natural.com/llms-full.txt — the full corpus, 164 pages, chunked per page and indexed with minisearch BM25 (search_docs)

  • docs.natural.com/api-reference/openapi.json — lazily parsed into an operations index; a single operation is pruned on demand — examples stripped, $refs resolved one level (lookup_endpoint)

No database, no vector store, no embeddings, no persistence. Just their own artifacts, indexed in memory.

Architecture

Layered so the documentation logic is portable, not welded to the host:

src/
  core/    parsing + search + OpenAPI pruning — platform-free (web-standard fetch only)
  tools/   the four tools as a transport-agnostic registry (zod shape + JSON Schema + handler)
  entry/
    worker.ts   Cloudflare Worker — stateless Streamable HTTP MCP (the live deployment)
    node.ts     stdio + official MCP SDK — offline/local fallback and test target

core/ and tools/ carry no platform dependency; the entry files are thin adapters. The Worker is stateless (no Durable Objects, no sessions) — each POST carries one JSON-RPC message, handled inline.

Develop

npm install
npm run build     # tsc -> dist/ (noEmitOnError gate)
npm run smoke     # spawn the stdio server, exercise all 4 tools + golden queries
npm start         # run the stdio server locally

npx wrangler dev      # run the Worker locally
npx wrangler deploy   # deploy the Worker

npm run smoke is the CI gate: it calls every tool and requires each golden integration query (idempotency, payment requests, vault, limits, errors) to surface the right page in the top 3.

See docs/EXAMPLES.md for real request/response transcripts.

Limitations

  • lookup_endpoint detail returns a representative subset of responses (primary 2xx + one error); other codes are listed under x-omitted-response-codes. Output is compact JSON capped at 14000 chars — enough for every current Natural operation.

  • First request after a cold start or cache expiry re-fetches the corpus/spec.

License

MIT © 2026 Jay Sharma. "Natural" and related marks belong to Natural AI, Inc.

Available Tools

4 tools
list_docsA

List Natural documentation sections and pages (title, slug, one-line description). No input. Use as a table of contents before read_doc.

Inputs: no named parameters.

lookup_endpointA

Look up Natural REST API endpoints from the OpenAPI spec. Query by path fragment, "METHOD /path", or keyword. detail=true on a single match returns the pruned operation: parameters, request body, and a representative subset of responses (primary 2xx plus one error; examples stripped, $refs resolved one level, other response codes listed under x-omitted-response-codes).

Inputs: query (required), detail.

read_docA

Fetch one Natural documentation page as markdown by slug (e.g. "guides/concepts/payments") or full docs URL. Truncated at 40000 chars.

Inputs: page (required).

search_docsA

Full-text search across Natural docs; returns ranked pages with title, slug, and a snippet. Use to find which page covers a topic.

Inputs: query (required), limit.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: listing docs, searching docs, reading a specific doc, and looking up API endpoints. No overlap or ambiguity.

    Naming Consistency5/5

    All tool names use a consistent verb_noun pattern in snake_case: list_docs, search_docs, read_doc, lookup_endpoint. No naming conventions are mixed.

    Tool Count5/5

    With 4 tools, the server is well-scoped for providing documentation and API endpoint lookup. Each tool is necessary and justified.

    Completeness4/5

    The tool surface covers listing, searching, reading docs, and querying endpoints. A minor gap is the lack of a way to list all endpoints without a search query, but the set is otherwise complete for its purpose.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides MCP tools to list and search OpenAI Agents SDK documentation, enabling LLMs to retrieve documentation topics and content via natural language queries.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Provides read-only MCP tools that let coding agents search and read bundled Bharosa documentation, API operation details, and SDK/cURL examples. It enables retrieving a contract, selecting grounded examples, and planning integrations without accounts, credentials, or live API calls.
      7
      42 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables coding agents to search public documentation, retrieve SDK snippets with verification status, and access published pricing and an llms.txt resource in a read-only, credential-free way.
      MIT