Unified

You run a unified MCP server that lets an AI orchestrator interpret natural language instructions, choose the right tool (Filesystem, Browser, GitHub), execute operations safely, and return structured results to a frontend chat interface. This server emphasizes secure, transparent, and modular tool usage, enabling you to perform developer-focused tasks with clear traces of tool calls and AI reasoning.

How to use

To use the MCP server with a client, connect your chat frontend to the backend orchestrator. You will send natural language prompts such as asking to summarize a GitHub repository, search the web for current information, or manipulate files within a sandbox. The orchestrator analyzes your request, decides which tool to invoke, runs it securely, and returns a structured result along with an explanation of the action taken.

Key capabilities you can rely on include:

• Intelligent tool selection to map tasks to the appropriate tool
• Secure filesystem operations limited to a sandbox directory
• Live web search and content extraction through a browser tool
• GitHub repository access for inspection and content retrieval
• Transparent tool-trace visualization in the frontend showing which tool was called and the payload returned

When you use the server, you will typically follow these patterns:

• Ask to summarize or analyze a repository, which routes to the GitHub tool
• Request live information from the web, which routes to the Browser tool
• Create or modify files within a restricted sandbox, which routes to the Filesystem tool

How to install

Prerequisites you need before installation include Node.js, Python, and access to a Gemini API key for the AI engine. You may also need a GitHub Personal Access Token if you plan to use the GitHub tool.

Set up the backend (FastAPI) and sandboxed tools, then run the frontend separately. Follow these steps to install and start the server.

cd backend
python -m venv .venv

# Activate the environment
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

pip install -r requirements.txt

# Install browser binaries for Playwright
playwright install chromium

# Create environment configuration
# GEMINI_API_KEY=your_google_gemini_api_key_here
# GITHUB_PAT=your_github_personal_access_token_here

cd ..
cd frontend
npm install

# Start the backend server in one terminal
uvicorn mcp_host_server:app --reload

# Start the frontend server in another terminal
npm run dev

# Backend runs by default at http://127.0.0.1:8000
# Frontend interface is typically at http://localhost:5173

Configuration and security notes

The Filesystem Tool is restricted to a sandbox directory to prevent unauthorized access to your system. This ensures all file operations happen within a safe, controlled area.

Environment variables you provide control access to the AI engine and integration with GitHub. Keep keys confidential and never expose them in client-side code.

Troubleshooting

Backend Not Responding: Ensure the FastAPI server is running, there are no runtime errors in the terminal, and environment variables are correctly configured.

Playwright Browser Errors: Verify that chromium was installed via Playwright, confirm system dependencies, and check the runtime environment for compatibility.

Windows-specific notes: If you encounter issues with asynchronous operations, ensure the event loop configuration in the backend startup is applied as described for Windows environments.

Notes on usage traces

The frontend presents a tool-call trace that includes the invoked tool, the raw payload from the backend, and an AI-generated explanation. This provides visibility into how the agent reaches its decisions and executes tasks.

Available tools

filesystem

Secure filesystem operations within a sandbox, including reading, writing, and listing files in a restricted directory

browser

Live web search and page extraction using a browser automation tool to visit sites and extract visible content

github

GitHub repository access to list repos, fetch file contents, and inspect metadata