MCP Knowledge Assistant

A read-only Model Context Protocol (MCP) server that lets an AI client search a knowledge base and retrieve complete source documents. The project starts with a small local prototype, then applies the same tool contract to semantic retrieval from an OpenAI vector store.

What this demonstrates

• MCP tool design with narrow search and fetch responsibilities

• Structured inputs and outputs using FastMCP and Pydantic

• Semantic retrieval over uploaded documents in an OpenAI vector store

• Document-level deduplication when vector search returns several matching chunks

• Streamable HTTP and stdio MCP transports

• End-to-end tool use through the OpenAI Responses API and a secure MCP tunnel

• Configuration through environment variables, with no credentials in source code

• Unit and protocol-level tests that do not make paid API calls

Related MCP server: File AI

Architecture

The following sequence shows the verified ChatGPT path. The tunnel client makes an outbound connection, so the local MCP server does not need a publicly exposed inbound port.

sequenceDiagram
    actor User
    participant ChatGPT
    participant Plugin as ChatGPT plugin
    participant Tunnel as OpenAI secure tunnel
    participant MCP as Local FastMCP server
    participant Store as OpenAI vector store

    User->>ChatGPT: Ask a question about the knowledge base
    ChatGPT->>Plugin: Call search(query)
    Plugin->>Tunnel: Send MCP tool request
    Tunnel->>MCP: Forward request over Streamable HTTP
    MCP->>Store: Run semantic search
    Store-->>MCP: Return matching chunks and file IDs
    MCP-->>Tunnel: Return deduplicated document results
    Tunnel-->>Plugin: Relay search results
    Plugin-->>ChatGPT: Provide document references

    ChatGPT->>Plugin: Call fetch(id)
    Plugin->>Tunnel: Send MCP tool request
    Tunnel->>MCP: Forward request over Streamable HTTP
    MCP->>Store: Retrieve the selected file content
    Store-->>MCP: Return parsed document content
    MCP-->>Tunnel: Return document and metadata
    Tunnel-->>Plugin: Relay fetched document
    Plugin-->>ChatGPT: Provide source content
    ChatGPT-->>User: Compose a grounded answer with a citation

api_client.py follows the same tunnel-to-server path, with the OpenAI Responses API acting as the MCP client instead of the ChatGPT plugin.

The repository also includes a fully local learning path:

Local demo client -> FastMCP server (stdio) -> data/documents.json

Both servers expose the same public tool contract:

Keeping discovery separate from retrieval avoids sending full documents before they are needed and gives the model stable document IDs to use in later calls.

Project structure

.
├── data/documents.json                   # Sample local knowledge base
├── sample_data/cats.pdf                  # Public-domain vector-store sample
├── src/mcp_knowledge_assistant/
│   ├── knowledge_base.py                 # Local keyword retrieval
│   ├── models.py                         # Shared response schemas
│   ├── server.py                         # Local stdio MCP server
│   └── vector_store_server.py            # OpenAI vector-store MCP server
├── tests/                                # Offline unit and MCP tests
├── demo_client.py                        # Local stdio demonstration
├── vector_store_demo_client.py           # Direct HTTP MCP demonstration
└── api_client.py                         # Responses API + secure tunnel demonstration

Requirements

• Python 3.11 or newer

• An OpenAI API project with billing enabled for the vector-store path

• The included sample PDF, or your own document, uploaded to an OpenAI vector store

• The OpenAI tunnel client only for the secure-tunnel demonstration

The local JSON server and the complete test suite require no API key.

Sample document attribution

The vector-store demonstration uses Cats: Their Points and Characteristics by W. Gordon Stables, Project Gutenberg eBook #43429. The sample PDF is hosted by OpenAI and was produced from the Project Gutenberg edition. See the PDF for the Project Gutenberg licence and applicable reuse terms.

Setup

Clone the repository, create a virtual environment, and install the project:

python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"

For OpenAI-backed examples, copy the environment template:

cp .env.example .env.local

Then add your own values to .env.local:

OPENAI_API_KEY=your_project_api_key
VECTOR_STORE_ID=vs_your_vector_store_id

.env.local, PyCharm settings, virtual environments, and local tunnel profiles are excluded from Git.

1. Run the local prototype

The first server uses stdio, so the MCP client launches it as a child process and communicates over standard input and output:

python demo_client.py

The demo discovers both tools, searches the sample JSON knowledge base, and fetches the selected document.

You can also start the server through its installed command:

mcp-knowledge-assistant

A silent, waiting process is normal for a stdio server that has no connected client.

2. Run the vector-store server

Upload sample_data/cats.pdf to an OpenAI vector store, then set OPENAI_API_KEY and VECTOR_STORE_ID in .env.local. You may substitute your own document and query if preferred. Start the Streamable HTTP server:

mcp-vector-store-assistant

By default, its MCP endpoint is:

http://127.0.0.1:8000/mcp

In a second terminal, test the endpoint directly:

python vector_store_demo_client.py

Vector search operates on chunks, so a long document may produce several matches with the same file ID. The MCP search tool deliberately collapses those matches into one document result. The fetch tool then retrieves and combines that document's parsed content for the model.

3. Call it through the Responses API

Download and configure tunnel-client

1. Create a tunnel in OpenAI Platform tunnel settings and copy its tunnel_id. Associate it with the Platform organization used by the API request and, for section 4, the intended ChatGPT workspace.

2. Download the archive for your operating system and CPU from the latest official tunnel-client release. For example, an Apple Silicon Mac uses the darwin-arm64 archive.

3. Extract the archive into the ignored .tools/tunnel-client directory and make the client executable:

mkdir -p .tools/tunnel-client
unzip /path/to/downloaded-tunnel-client.zip -d .tools/tunnel-client
chmod +x .tools/tunnel-client/tunnel-client
.tools/tunnel-client/tunnel-client --version

Create an ignored profile that connects the OpenAI-hosted tunnel to this project's local Streamable HTTP endpoint:

mkdir -p .tools/tunnel-profiles
.tools/tunnel-client/tunnel-client init \
  --profile cats-vector-store \
  --profile-dir .tools/tunnel-profiles \
  --tunnel-id tunnel_your_tunnel_id \
  --mcp-server-url http://127.0.0.1:8000/mcp

This creates .tools/tunnel-profiles/cats-vector-store.yaml. Do not commit that profile because it contains your tunnel ID. Add the same ID and a runtime API key from OpenAI Platform API keys to .env.local:

MCP_TUNNEL_ID=tunnel_your_tunnel_id
CONTROL_PLANE_API_KEY=your_runtime_api_key

The tunnel ID identifies the tunnel. CONTROL_PLANE_API_KEY authenticates the locally running tunnel client to OpenAI. Validate the configuration after the MCP server is running:

.tools/tunnel-client/tunnel-client doctor \
  --profile-file .tools/tunnel-profiles/cats-vector-store.yaml

Run the demonstration from three terminals opened at the project root. Keep the first two processes running while you start the third.

Terminal 1: start the MCP server

mcp-vector-store-assistant

This starts the local Streamable HTTP endpoint at http://127.0.0.1:8000/mcp.

Terminal 2: start the secure tunnel

The Python programs load .env.local automatically, but the tunnel-client binary does not. Export the variables from that file into this terminal first:

set -a
source .env.local
set +a

Then start the tunnel client using your local binary and profile. For example:

.tools/tunnel-client/tunnel-client run \
  --profile-file .tools/tunnel-profiles/cats-vector-store.yaml

The profile tells tunnel-client which tunnel and local MCP endpoint to use. CONTROL_PLANE_API_KEY authenticates the running tunnel client to OpenAI.

Terminal 3: call the Responses API

python api_client.py

api_client.py loads OPENAI_API_KEY and MCP_TUNNEL_ID from .env.local. Its Responses API request declares only the read-only search and fetch MCP tools. The request travels through the running tunnel to the local server, which searches the vector store and returns the selected source for the model's answer.

4. Test it from ChatGPT

With the vector-store server and tunnel client still running, create or refresh a developer-mode ChatGPT plugin associated with the same tunnel and ChatGPT workspace. Add the plugin to a new conversation and ask ChatGPT to search the knowledge base, fetch the most relevant document, and cite it in the answer.

This path was verified on September 11, 2026 with FastMCP 3.4.7 and tunnel-client v0.0.14 using the Streamable HTTP endpoint. ChatGPT invoked both search and fetch, retrieved content from cats.pdf, and produced a sourced answer. An earlier v0.0.11 test entered a reconnect loop; the successful v0.0.14 retest is documented in openai/tunnel-client#41.

Tests

Run all tests with:

pytest

The tests cover local ranking and fetching, MCP tool discovery, vector-result deduplication, content assembly, and input validation. OpenAI calls are mocked, so the suite is repeatable and does not consume API credits.

Design decisions and scope

• Read-only first: neither MCP tool changes files or external state.

• Stable compatibility contract: search(query) returns document references; fetch(id) returns complete content and metadata.

• Document results, not chunk results: chunks are retrieval evidence inside the vector store, while the MCP client receives stable file IDs.

• MCP is an abstraction layer: for a single OpenAI-hosted vector store, the Responses API's built-in File Search tool is simpler. MCP becomes useful when the same retrieval interface must serve multiple clients, hide backend details, or later add authorization and domain logic.

• Verified integration boundary: the local servers, direct MCP clients, Responses API path, and a developer-mode ChatGPT plugin were exercised through the secure tunnel. This repository does not claim a deployed public server or a published ChatGPT app.

Security notes

• Never commit .env.local, API keys, tunnel runtime keys, or organization IDs.

• Use project-scoped credentials and grant only the permissions required.

• Keep the local MCP server bound behind the secure outbound tunnel rather than opening an inbound firewall port.

• Review tool permissions before adding any write or consequential action.

References

• OpenAI MCP guide

• OpenAI File Search guide

• OpenAI secure MCP tunnels guide

• FastMCP documentation