MCP Retrieval Sidecar
FastMCP-based retrieval agent that exposes search_documents, get_documents, and health_check tools over the streamable HTTP transport. Designed to run as a sidecar for Dify (1.9+) but usable with any MCP-compatible host.
Features
- Async HTTP client with retry/backoff for a synchronous REST backend.
- TTL caching for search responses to reduce backend load.
- Prompt templates for quick answers and query refinement.
/healthzand/configauxiliary routes sharing the MCP server.- Comprehensive tests: mocked HTTP layer plus integration suite against a FastAPI stub.
Requirements
- Python 3.11+
- uv for dependency management and task running
- (Optional) Docker & Docker Compose for container deployments
Getting Started
- Create the virtual environment and install dependencies:
bash uv venv .venv uv pip install fastmcp httpx cachetools pytest pytest-asyncio fastapi uvicorn - Activate the environment (bash/zsh):
bash source .venv/bin/activate - Run the MCP server locally:
bash uv run python server.py # Server listens on http://127.0.0.1:8080/mcp/ - Prefer to keep it next to another container? Use the provided Compose file to launch the sidecar:
bash docker compose up -d mcp-retrieval
Set env vars in.envor inline on the command (ENDPOINT_URL,MCP_SERVER_API_KEY, etc.), and adjust the Compose-defined network to match the one your MCP host uses so the sidecar can resolve its internal services.
Environment variables are documented in server.py; key ones include:
| Variable | Description | Default |
|---|---|---|
ENDPOINT_URL |
Base URL of the external REST search API | (required) |
API_KEY |
Bearer token for the backend | empty |
MCP_SERVER_API_KEY |
Bearer token clients must send to reach this MCP server | empty |
REQUEST_TIMEOUT_S |
Per-request timeout | 20 |
PROXY_URL |
HTTP(S) proxy URL (for corporate MITM) | empty |
CACHE_TTL_S |
Search cache TTL (seconds) | 60 |
CACHE_MAX_ITEMS |
Search cache max entries | 500 |
LOG_LEVEL |
Log level (INFO, DEBUG, …) |
INFO |
MCP Host Example
To connect this server from Dify’s dify-plugin-tools-mcp_sse plugin, add an entry to the plugin’s MCP Servers configuration pointing at the sidecar’s streamable HTTP endpoint and include the bearer token defined in MCP_SERVER_API_KEY:```json
{
"mcpServers": {
"retrieval-sidecar": {
"transport": "streamable_http",
"url": "http://127.0.0.1:8080/mcp",
"headers": {
"Authorization": "Bearer ${MCP_SERVER_API_KEY}"
},
"timeout": 50
}
}
}
Set `MCP_SERVER_API_KEY` in your `.env` (and load it into the Dify plugin’s environment) so the plugin can send the expected bearer token when calling this MCP server.
## Testing
The Make targets wrap the preferred `uv` commands:
- `make test` — full suite (`uv run pytest -q`)
- `make test-unit` — mocked transport tests against `tests/test_search_mock.py`
- `make test-integration` — integration tests against the stub API
- `make test-e2e` — runs the integration suite; auto-starts the stub if `ENDPOINT_URL` is unset, otherwise reuses the provided endpoint
- `make stub` — run the FastAPI stub on `127.0.0.1:18080`
Direct invocation works too:```bash
uv run pytest -q
Docker
Build and run the sidecar with the provided artifacts:```bash
docker compose build
docker compose up
Expose runtime configuration via environment variables or a `.env` file referenced by Compose. The service joins an external network named `dify_network` by default (override with `DIFY_DOCKER_NETWORK`).
For E2E testing inside the compose network, bring up the stub service with the supplemental compose file and point the MCP container at it:```bash
docker compose -f docker-compose.stub.yaml up -d stub-api
docker compose run --rm \
-e ENDPOINT_URL=http://mcp-retrieval-stub:18080 \
mcp-retrieval \
make test-e2
The command above runs the same integration suite inside the containerized environment, automatically skipping the stub bootstrap because ENDPOINT_URL is provided. Shut the stub down afterwards with docker compose -f docker-compose.stub.yaml down.
To run both the MCP server and stub together (e.g. for local QA), combine the compose files:bash
docker compose -f docker-compose.yaml -f docker-compose.stub.yaml up -d
This keeps the stub optional in production while making it easy to opt in for tests.
Development Tips
tests/test_search_mock.pyuseshttpx.MockTransportfor deterministic unit tests.tests/test_integration_stub.pydepends onuvicorn; the fixture launchesstub_api/app.pyin a background thread.- Logging is structured JSON; avoid printing secrets—the
/configroute masks sensitive values automatically.
