How do I use MCP Demo - Document Search Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP Demo - Document Search Server search my docs for async Python" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

MCP Demo - Document Search Server

by simplifyaimm

Overview Schema Related Servers Score Discussions

Python

Local

MCP Demo: Document Search Server

Companion repo for the YouTube video "MCP Explained for Engineers — Not Just Another API Wrapper"

A production-style MCP server that lets Claude Desktop search your local documents. No LangChain. No heavy frameworks. Plain Python + the official MCP SDK.

Clone → install → add to Claude Desktop → done in under 10 minutes.

What is MCP?

MCP (Model Context Protocol) is an open standard for connecting AI models to external tools and data sources. Think of it as a USB-C port for AI — one protocol, many connectors.

The problem it solves: every AI integration used to be custom code. You'd write OpenAI function calling differently than Anthropic tool use, differently again for Gemini. MCP standardizes the interface so a single server works with any compatible client.

┌─────────────────┐    JSON-RPC over stdio    ┌──────────────────────┐
│  Claude Desktop │ ◄──────────────────────► │  Your MCP Server     │
│  (MCP Client)   │                           │  (this repo)         │
│                 │   list_tools()            │                      │
│                 │   call_tool("search_documents", {query: "..."})  │
│                 │ ◄─── results ─────────── │  TF-IDF search over  │
│                 │                           │  local .md/.txt docs │
└─────────────────┘                           └──────────────────────┘

The server speaks JSON-RPC 2.0 over stdin/stdout. Claude Desktop manages the connection. You write Python functions; the protocol handles the rest.

Related MCP server: smart-search

What This Demo Does

The server exposes three tools to Claude:

Tool	What it does
`search_documents`	TF-IDF keyword/phrase search, returns ranked results with snippets
`get_document`	Returns the full text of any indexed document
`list_documents`	Lists all documents with word counts

Five sample engineering documents are included (async Python, API design, Docker, Git, system design). Drop any .md or .txt files into documents/ and restart the server to index them.

Quick Start

Prerequisites

Python 3.10 or higher
Claude Desktop installed (for the full demo)
pip or uv

Step 1 — Clone and install

git clone https://github.com/YOUR_USERNAME/mcp-demo.git
cd mcp-demo
pip install -r requirements.txt

Step 2 — Run the smoke test

This verifies the search engine works correctly without needing Claude Desktop:

python test_server.py

Expected output:

=== MCP Demo — Search Engine Smoke Test ===

Indexed 5 document(s) from .../documents

  [PASS] at least 5 documents indexed (got 5)
  [PASS] all documents have >50 words
Search relevance checks:
  [PASS] 'async await event loop' → python_async.md (got python_async.md)
  [PASS] 'REST API versioning idempotent' → api_design.md (got api_design.md)
  ...

All checks passed.

Step 3 — Connect to Claude Desktop

Find your Claude Desktop config file:

OS	Path
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

Add this block to the config (replace the path):

{
  "mcpServers": {
    "doc-search": {
      "command": "python",
      "args": ["-m", "server.main"],
      "cwd": "/absolute/path/to/mcp-demo"
    }
  }
}

Windows example:

{
  "mcpServers": {
    "doc-search": {
      "command": "python",
      "args": ["-m", "server.main"],
      "cwd": "C:\\Users\\you\\mcp-demo"
    }
  }
}

Restart Claude Desktop. You should see a hammer icon (🔨) in the chat input bar — that confirms MCP tools loaded successfully.

Step 4 — Try it in Claude

Ask Claude any of these to see MCP working:

What documents do I have indexed?

Search my docs for information about async Python and the event loop

Find everything about Docker multi-stage builds and summarize the key points

Compare what my docs say about caching strategies

Watch Claude automatically invoke list_documents, search_documents, and get_document as needed — reasoning over your local files without any copy-paste.

How It Works

The MCP Handshake

When Claude Desktop starts, it launches your server as a subprocess and sends an initialize request. The server responds with its capabilities. Claude then calls tools/list to discover available tools and their schemas.

All subsequent calls use the same stdio pipe:

Claude Desktop                    server/main.py
     │                                  │
     │── initialize ──────────────────► │
     │◄─ initialized ─────────────────  │
     │── tools/list ────────────────── ►│
     │◄─ [search_documents, ...] ─────  │
     │                                  │
     │   (user asks a question)         │
     │── tools/call ────────────────── ►│  search_documents(query="async")
     │◄─ result ──────────────────────  │  TF-IDF scores → ranked results

The Search Engine

server/search.py implements TF-IDF scoring from scratch — no scikit-learn, no embeddings:

TF (term frequency): how often a term appears in a document, normalized by document length
IDF (inverse document frequency): log(N / df) — penalizes terms that appear in every document
Score: sum of TF×IDF for each query term present in the document

This is the same algorithm that powered early web search. It works well for keyword queries over small document collections and has zero runtime dependencies.

FastMCP

server/main.py uses FastMCP — the high-level API from the official MCP SDK:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("doc-search")

@mcp.tool()
def search_documents(query: str, max_results: int = 5) -> str:
    """Ranked keyword search across indexed documents."""
    ...

mcp.run()  # starts stdio transport

FastMCP introspects your function signatures to generate the JSON Schema that Claude uses to understand what arguments each tool accepts. The docstring becomes the tool description shown to the model.

Repository Structure

mcp-demo/
├── server/
│   ├── main.py          # FastMCP server — 3 tools, ~60 lines
│   └── search.py        # TF-IDF engine — no ML dependencies
├── documents/
│   ├── python_async.md
│   ├── api_design.md
│   ├── docker_guide.md
│   ├── git_workflow.md
│   └── system_design.md
├── test_server.py                    # smoke test (no Claude needed)
├── claude_desktop_config_example.json
├── requirements.txt                  # mcp[cli]>=1.0.0
└── pyproject.toml

Adding Your Own Documents

Drop any .md or .txt files into documents/ and restart Claude Desktop (which restarts the server subprocess). The index rebuilds at startup.

Ideas:

Your team's runbooks and internal docs
Architecture decision records (ADRs)
Personal notes exported from Notion or Obsidian
API documentation in markdown format

Troubleshooting

No hammer icon in Claude Desktop

Check the config path is correct for your OS
Verify the cwd path is absolute and the directory exists
Check Claude Desktop logs: ~/Library/Logs/Claude/ (macOS) or Event Viewer (Windows)

ModuleNotFoundError: No module named 'mcp'

Make sure you installed dependencies: pip install -r requirements.txt
If using a virtual environment, Claude Desktop needs to use the same Python: replace "command": "python" with the full path to your venv's Python

Server starts but returns no results

Run python test_server.py to verify the search engine directly
Check that documents/ contains .md or .txt files

Testing the server manually (without Claude Desktop)

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}}}' | python -m server.main

Going Further

Add semantic search: replace TF-IDF with embeddings using sentence-transformers and cosine similarity for better recall on paraphrased queries
Add resources: expose documents as MCP Resources (read-only, URI-addressed) in addition to tools — clients can subscribe to resource changes
Add prompts: package common workflows as MCP Prompts that pre-fill Claude's context
Connect other clients: the same server works with Cursor, Zed, or any MCP-compatible editor

Official MCP docs: https://modelcontextprotocol.io
MCP Python SDK: https://github.com/modelcontextprotocol/python-sdk

Available Tools

3 tools

get_documentA

Retrieve the full text of a document by filename. Call list_documents first if you're unsure of the exact filename.

ParametersJSON Schema

Name	Required	Description	Default
`filename`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the burden. It mentions 'full text' but does not disclose behavior like error handling, size limits, or authentication requirements. It is adequate for a simple tool but lacks depth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: first states purpose, second provides usage hint. No wasted words, perfectly front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with one parameter and an output schema (not shown). The description covers the core action and pre-requisite step, but omits details like error handling or file-not-found behavior. Still, it is fairly complete for the simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter 'filename' has no schema description (0% coverage). The description adds 'by filename' but does not explain format, case sensitivity, or path requirements. For a simple retrieval, it is minimally sufficient.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Retrieve the full text of a document') and the resource ('by filename'), distinguishing it from siblings 'list_documents' (listing files) and 'search_documents' (searching).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidance: 'Call list_documents first if you're unsure of the exact filename,' telling the agent when to use an alternative tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_documentsA

List every document currently in the index, along with its word count.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It accurately describes a read-only operation that returns all documents and word counts. No hidden behaviors are mentioned, but for this straightforward task, it is sufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise, using a single sentence that conveys the purpose and output. No wasted words, front-loaded with the action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (no parameters, output schema exists), the description is complete. It explains what the tool does and what it returns, leaving no ambiguity for selection or invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has no parameters, so schema coverage is 100% trivially. The description adds no parameter information, but baseline is 4 for zero parameters. The description aligns with the tool's function.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists every document with word count. The verb 'list' and resource 'documents' are specific. While siblings exist (get_document, search_documents), the description implies a full index listing, but does not explicitly differentiate.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus siblings. The description 'list every document' implies it is for unfiltered retrieval, but does not mention alternatives or situations to avoid. This is adequate for a simple tool with no parameters.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_documentsA

Search indexed documents by keyword or phrase using TF-IDF ranking. Returns up to max_results results, each with a relevance score and excerpt.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes
`max_results`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses return structure (up to max_results results with relevance score and excerpt) and behavior (limit via max_results). Does not mention auth, rate limits, or side effects, but for a search tool this is sufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no redundancy, front-loaded with action. Every word adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has an output schema (not shown), the description explains key return fields (relevance score, excerpt). Parameter count is low and semantics are explained. Missing some details like what happens if max_results omitted (default in schema), but overall complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% (no descriptions in schema). The description adds meaning: 'by keyword or phrase' explains query usage, and 'up to max_results' explains its purpose. This goes beyond the schema's bare field names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description specifies the verb 'Search', the resource 'indexed documents', and the method 'TF-IDF ranking'. It clearly distinguishes from siblings 'get_document' (single doc retrieval) and 'list_documents' (listing all docs).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for keyword/phrase search but does not explicitly state when to use versus alternatives or provide any 'when not to use' guidance. Sibling names provide context but description lacks explicit guidelines.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0

Disambiguation5/5

Each tool has a distinct purpose: listing all documents, searching by keyword, and retrieving full text. There is no overlap or ambiguity.

Naming Consistency5/5

All tools follow a consistent verb_noun snake_case pattern: get_document, list_documents, search_documents.

Tool Count5/5

With 3 tools, the server is well-scoped for document search: list, search, retrieve. Not too few or too many.

Completeness5/5

Core functionality is fully covered: indexing overview, search with ranking, and full-text retrieval. No gaps for a search-focused server.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

mcp A
ai.llmse
Public MCP server for the LLM Search Engine
Search RAG Systems Developer Tools
102
saagarpatel.dev Portfolio A
io.github.saagpatel
Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.
Search Documentation Access
82
Mirror Memory MCP Server
io.github.Tr1ckyMag1ca1
Personal knowledge base MCP server with semantic search, auto-categorization, metadata extraction
Knowledge & Memory Search Note Taking
2
forkast-mcp-docs A
io.github.ForkastPredict
MCP server for querying Forkast documentation
Documentation Access Search Developer Tools
42

Related MCP Servers

MCP Data Server
Vector Databases Search Knowledge & Memory
hkonda015
A
license
Not graded
quality
D
maintenance
Indexes local files (PDF, TXT, CSV, Markdown) with embeddings for semantic search. Provides both CLI and MCP server interfaces so Claude Desktop can search and read your local documents.
Updated a year ago (2025-08-22 15:01 UTC)
MIT
smart-search
RAG Systems Vector Databases File Systems
ekmungi
F
license
Not graded
quality
D
maintenance
A local-first MCP server that enables semantic search over PDF and DOCX documents using structure-aware parsing and vector storage. It allows users to query their local knowledge base through Claude Code without cloud dependencies or GPU requirements.
Updated 5 months ago (2026-04-07 06:43 UTC)
vectorise-mcp
RAG Systems Search Vector Databases
jameslovespancakes
A
license
Not graded
quality
D
maintenance
Local MCP server that indexes folders of documents into a hybrid vector + keyword search index for Claude Desktop, with support for PDFs, Office files, and images via OCR.
Updated 4 months ago (2026-05-08 18:34 UTC)
MIT
local-document-rag-agent
RAG Systems Vector Databases Search
iupulk
F
license
Not graded
quality
C
maintenance
MCP server enabling Claude Desktop to answer questions from local Word and PDF documents by searching a vector index built from their contents.
Updated 2 months ago (2026-06-27 06:35 UTC)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/simplifyaimm/mcp-demo'

If you have feedback or need assistance with the MCP directory API, please join our Discord server