MCP Main and Proxy Server

You set up and run an MCP server ecosystem that coordinates multiple specialized services, allowing you to route requests between components, discover available tools, and build high-level pipelines for RAG workflows and document processing.

How to use

You interact with the MCP server through a client that discovers all connected servers and their tools, then requests specific actions via the router. Start by ensuring the main registry is reachable, then connect your client to the MCP cluster. You can use the proxy MCP server to pre-process data for RAG and to obtain a consolidated list of servers and tools. When you issue a task, the main server routes it to the appropriate specialized server (for embedding, PDF extraction, ranking, vector storage, SQL access, LLM generation, markup, or transcription) and aggregates results for you.

How to install

Prerequisites: you need Python and Docker to run the main MCP server components. Create a Python virtual environment, install dependencies, and start the main server or run via Docker.

# 1) Create a virtual environment
python -m venv venv

# 2) Activate the environment
./venv/Scripts/activate

# 3) Install dependencies
pip install -r requirements.txt

# Start the main MCP server (example)
fastmcp run ./main_server.py:main_mcp_server --transport http

Additional sections

Configuration and runtime are organized around a main MCP registry and optional specialized servers. The main registry coordinates servers, routes requests, monitors status, and aggregates tool information. You can add new FastMCP servers by importing them in the main server configuration and ensuring each new server implements a health_check method.

Environment and run options include a set of explicit commands and file paths you can use to start the main server, the proxy that forwards to the registry, and auxiliary components for RAG workflows.

{
  "mcpServers": {
    "main_registry": {
      "url": "http://localhost:8000/mcp/",
      "type": "http",
      "args": []
    },
    "proxy_server": {
      "type": "stdio",
      "command": "fastmcp",
      "args": ["run", "./proxy_mcp_server/proxy_mcp_server.py:proxy_mcp_server"],
      "env": []
    },
    "main_server": {
      "type": "stdio",
      "command": "fastmcp",
      "args": ["run", "./main_server.py:main_mcp_server", "--transport", "http"],
      "env": []
    },
    "docker_main": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "--rm", "-p", "8000:8000", "--env-file", ".env", "mcp-main-server"],
      "env": []
    },
    "rag_inference": {
      "type": "stdio",
      "command": "python",
      "args": ["rag_inference/RAG workflow.py", "<collection_name>"],
      "env": []
    }
  }
}

Notes on environment and endpoints

Set the API keys and URLs for each connected server as shown. This ensures that each specialized server can be reached by the main MCP server and that health checks succeed.

# Essential environment variables you will configure
MAIN_SERVER_API_KEY=...

# Embedding server
EMBEDDING_API_KEY=...
EMBEDDING_URL=...
EMBEDDING_MODEL_NAME=...
EMBEDDING_URL_MODELS=...
EMBEDDING_HEALTH_URL=...

# PDF extractor
PDF_EXTRACTOR_URL=...
PDF_HEALTH_URL=...

# Reranker
RERANK_URL=...
RERANK_MODEL=...
RERANK_HEALTH_URL=...

# Qdrant
QDRANT_URL=...
QDRANT_API_KEY=...
QDRANT_HEALTH_CHECK_URL=...

# PostgreSQL
POSTGRES_USER=...
POSTGRES_PASSWORD=...
POSTGRES_HOST=...
POSTGRES_DB=...

# LLM service
LLM_SERVICE_API_KEY=...
LLM_SERVICE_MODEL=...
LLM_SERVICE_CHAT_COMPLETIONS_URL=...
LLM_SERVICE_MODELS_URL=...
LLM_SERVICE_COMPLETIONS_URL=...
LLM_SERVICE_HEALTH_URL=...

# MarkUp
MARKUP_API_KEY=...
MARKUP_GET_METHODS_URL=...
MARKUP_PROCESS_TEXT_URL=...
MARKUP_PROCESS_FILE_URL=...
MARKUP_HEALTH_CHECK_URL=...

# Transcribe
TRANSCRIBE_API_KEY=...
TRANSCRIBE_UPLOAD_AUDIO=...
TRANSCRIBE_HEALTH_URL=...

Security and troubleshooting notes

Keep API keys secret and rotate them periodically. Ensure health_check endpoints respond as expected before routing traffic. If a server becomes unavailable, use health_check_servers to verify the status and re-route requests as needed.

Available tools

get_server_and_tools

Return a list of all connected MCP servers and their tools from the registry

router

Route a request to a specific server and tool with given parameters

health_check_servers

Check the health status of all registered MCP servers

preprocessing_data_for_rag

Prepare PDF/text data for RAG by pre-processing and creating a Qdrant collection; returns the collection name

embedding_generate

Generate vector embeddings for input text (Embedding server)

embedding_batch_generate

Generate embeddings for a batch of inputs (Embedding server)

embedding_get_models

List available embedding models (Embedding server)

document_convert_to_markdown

Convert PDFs to Markdown (PDF extract server)

document_get_supported_formats

List formats supported for PDF conversion (PDF extract server)

rerank_documents

Rank documents using the Reranker server

vector_create_collection

Create a new vector collection in Qdrant

vector_get_collection_info

Get information about a Qdrant collection

vector_upsert_points

Upsert vectors into a Qdrant collection

vector_search

Search for vectors in a Qdrant collection

vector_delete_points

Delete vectors from a Qdrant collection

postgres_execute_query

Execute SQL queries against PostgreSQL (PostgreSQL server)

postgres_get_schema

Inspect PostgreSQL schema

postgres_create_table

Create a PostgreSQL table

postgres_insert_data

Insert data into PostgreSQL

llm_chat_completion

Chat-based LLM completion (LLM server)

llm_get_models

List available LLM models

llm_stream_completion

Streaming LLM completion

markup_get_methods

Retrieve available markup methods

markup_process_text

Process text with markup service

markup_process_file

Process file with markup service

transcribe_audio

Transcribe audio with the Transcribe server

transcribe_get_status

Check transcription status

transcribe_get_result

Get transcription result