Needle MCP Server: RAG Search and Retrieval

Overview

Needle MCP Server is an implementation of the Model Context Protocol (MCP) that provides a lightweight, production-ready backend for retrieval-augmented generation (RAG). It sits between your vector store, embedding/model providers, and application logic to deliver fast document search and context retrieval for downstream LLM calls. The server handles ingestion, embedding, indexing, and retrieval so applications can focus on composition and prompting.

This server is useful when you need deterministic, secure, and scalable access to contextual document slices for LLM prompts. Typical uses include knowledge-base search, customer support augmentation, legal and contract review, and any workflow that benefits from combining vector search with large language models.

Features

• Embedding pipeline: convert documents into embeddings using pluggable embedding providers
• Vector index adapters: support for common vector stores and local indexes (FAISS, Milvus, Pinecone, Weaviate, etc.)
• Document ingestion and chunking with metadata preservation
• Query-time retrieval with configurable similarity, score thresholds, and top-k results
• Role- and key-based access control and optional API key protection
• Streaming-friendly responses for low-latency applications
• Simple HTTP API compatible with automated orchestration and serverless deployments
• Configurable batching and concurrency for production throughput

Installation / Configuration

Minimum options: run with Docker (recommended) or run from source in Python/Node environments depending on the project distribution.

Run with Docker

# Pull the official image (replace `needle-mcp` with the real image name if provided)
docker run -d \
  -p 8080:8080 \
  -e MCP_EMBEDDING_PROVIDER="openai" \
  -e OPENAI_API_KEY="sk-..." \
  -e VECTOR_DB="faiss" \
  --name needle-mcp \
  needle-ai/needle-mcp:latest

Run with docker-compose

version: '3.8'
services:
  needle-mcp:
    image: needle-ai/needle-mcp:latest
    ports:
      - "8080:8080"
    environment:
      MCP_EMBEDDING_PROVIDER: openai
      OPENAI_API_KEY: ${OPENAI_API_KEY}
      VECTOR_DB: faiss
    volumes:
      - ./data:/data

Basic environment variables

Configuration file The server can be configured via environment variables or a JSON/YAML configuration file. Typical fields include embedding provider settings, vector database credentials, chunk size, and indexing options.

Available Tools / Resources

The server exposes a simple HTTP API and often includes a small CLI for administrative operations:

• REST endpoints (examples)

  • POST /ingest — upload files or URLs to index
  • POST /search — query and retrieve nearest document contexts
  • GET /health — basic health check
  • POST /admin/reindex — trigger reindexing/maintenance

• Connectors

  • Storage: local filesystem, S3/GCS-compatible buckets
  • Vector DBs: FAISS (local), Pinecone, Milvus, Weaviate
  • Embedding providers: OpenAI, Cohere, Hugging Face, locally hosted encoders

• Client integration

  • Use any HTTP client (curl, axios, fetch) or wrap the API in SDKs for Node/Python

Use Cases

1. Customer support augmentation

   • Ingest knowledge-base articles, FAQs, and chat transcripts.
   • At query time, retrieve top-k snippets and pass them as context to an LLM to produce accurate, grounded responses.

2. Contract review

   • Ingest PDFs and document text, chunk by clauses, and index with metadata (contract ID, parties, dates).
   • Search for clauses similar to a query like “limitation of liability” and surface exact clause text and source.

3. Domain-specific search for product docs

   • Build a search layer over developer docs and API references to return concise, relevant code snippets and paragraphs.
   • Combine retrieved context with a code-aware LLM to generate examples or troubleshooting steps.

4. Monitoring and compliance

   • Periodically reindex logs, policies, and compliance documents to enable fast forensic search and evidence retrieval.

Quick example: ingest and query with curl

Ingest a text document

curl -X POST "http://localhost:8080/ingest" \
  -H "Authorization: Bearer ${MCP_API_KEY}" \
  -F "file=@./guide.pdf" \
  -F "source=guides"

Search for relevant context

curl -X POST "http://localhost:8080/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${MCP_API_KEY}" \
  -d '{
    "query": "how to reset API credentials",
    "top_k": 5,
    "filters": {"source": "guides"}
  }'

Sample response (trimmed)

{
  "query": "how to reset API credentials",
  "results": [
    {"id": "doc1#chunk3", "score": 0.92, "text": "To reset your API key, go to Settings → API keys..."},
    {"id": "doc2#chunk1", "score": 0.87, "text": "If you lose access, contact support..."}
  ]
}

Next steps

• Choose and configure a vector backend that fits your scale and hosting constraints (local FAISS for dev, managed Pinecone/Milvus for production).
• Select an embedding provider and set API credentials in environment variables.
• Integrate the /search responses into your prompt composition flow to enable RAG-enabled LLM requests.

For full source, deployment examples, and advanced configuration options, see the project repository on GitHub: https://github.com/needle-ai/needle-mcp.