Overview

This MCP (Model Context Protocol) server provides a lightweight HTTP service that retrieves contextual items from a Pinecone vector index and returns them in a format suitable for retrieval-augmented generation (RAG) workflows and assistant integrations. It sits between your model runtime and Pinecone, exposing an MCP-compatible endpoint so models or orchestration layers can request relevant context for a user query without talking directly to Pinecone.

Running an MCP server centralizes retrieval logic, enforces access controls, and makes it easier to tune retrieval parameters (top-k, namespaces, filters) in one place. Developers integrating assistants or conversational agents can use this server to fetch semantic context quickly and at scale, then stitch that context into prompts passed to language models.

Features

MCP-compatible HTTP API for context retrieval
Pinecone-backed vector search (configurable index and namespace)
Configurable retrieval parameters: top_k, namespace, filters
Docker-ready and simple local development workflow
Environment-driven configuration for secure deployments
Returns context items with id, score, metadata and text suitable for RAG
Lightweight and designed to be used alongside any model provider

Installation / Configuration

Prerequisites:

A Pinecone account and a created index containing embeddings
Docker (recommended) or Node.js/your chosen runtime to run the server locally

Clone the repository and run with Docker:

git clone https://github.com/pinecone-io/assistant-mcp.git
cd assistant-mcp

# Run with Docker (example)
docker build -t assistant-mcp .
docker run -p 8080:8080 \
  -e PINECONE_API_KEY="your-pinecone-api-key" \
  -e PINECONE_ENVIRONMENT="us-west1-gcp" \
  -e PINECONE_INDEX="assistant-index" \
  -e MCP_PORT=8080 \
  assistant-mcp

Run locally with environment variables (example .env):

PINECONE_API_KEY=your-pinecone-api-key
PINECONE_ENVIRONMENT=us-west1-gcp
PINECONE_INDEX=assistant-index
MCP_PORT=8080
DEFAULT_TOP_K=5

Start (Node/npm example):

npm install
npm run build
npm start

Environment variables

Variable	Description	Example
PINECONE_API_KEY	API key to authenticate with Pinecone	sk-xxx
PINECONE_ENVIRONMENT	Pinecone environment/region	us-west1-gcp
PINECONE_INDEX	Name of the Pinecone index to query	assistant-index
MCP_PORT	Port the MCP server listens on	8080
DEFAULT_TOP_K	Default number of nearest neighbors to return	5

Available Resources

GitHub repository: https://github.com/pinecone-io/assistant-mcp
Example indexer script (sample included in repo) to embed and upsert documents into Pinecone
Dockerfile for containerized deployment
Sample curl and Postman collections to exercise the MCP endpoints (check the repo /examples directory)
Basic logging and error responses for integration debugging

API (Typical usage)

The server exposes an HTTP endpoint to retrieve context for a natural language query. Example request/response:

Request (POST /mcp/retrieve):

POST /mcp/retrieve HTTP/1.1
Content-Type: application/json

{
  "query": "How do I reset my password?",
  "top_k": 4,
  "namespace": "user-help"
}

Response (200):

{
  "query": "How do I reset my password?",
  "results": [
    {
      "id": "doc-123",
      "score": 0.92,
      "metadata": { "source": "faq", "section": "account" },
      "text": "To reset your password go to /account/reset and follow the instructions..."
    },
    ...
  ]
}

Adjustable parameters include top_k (number of returned items) and namespace (sub-index grouping in Pinecone). Filters based on metadata can also be supported if configured.

Use Cases

Conversational assistants: Fetch relevant passages to include in prompt context so the assistant can answer user questions with up-to-date domain knowledge.
Customer support: Retrieve troubleshooting steps or KB articles relevant to a support ticket to assemble a response or suggested actions.
Code/documentation search: Surface precise code snippets or API docs matching a developer’s query before generating a summary or an explanation.
Summarization workflows: Pull related documents for multi-document summarization or to augment summaries with factual source excerpts.

Concrete example workflow:

Ingest product docs into Pinecone (embed and upsert).
User asks a question in chat.
Chat frontend calls the MCP server with the query and namespace “product-docs”.
MCP server queries Pinecone, returns the top-K matching passages.
The chat backend composes a prompt combining system instructions, the returned passages, and the user query, then calls the model.

Tips for Production

Protect the MCP endpoint behind an auth layer (API keys, mTLS or IAM) to avoid unrestricted access to your Pinecone key.
Tune top_k and embedding model to balance latency and relevance.
Use namespaces to separate different

MCP Server for Pinecone Assistant Context Retrieval