📚 MCP Server Integration Guide

This guide provides instructions on how to configure your Fullstack Context MCP Server with various AI clients (Claude Desktop, Cursor, VS Code/Cline, Gemini CLI).

⚠️ Prerequisites

1. Absolute Paths Only: MCP clients rarely understand relative paths like . or ~. Always use full paths (e.g., /Users/name/project or C:\Users\name\project).
2. Python Environment: Ensure mcp is installed in the python environment you are pointing to.

---

🛑 IMPORTANT: Workspace Restrictions (Sandboxing)

Read this if you use VS Code, Cursor, or Windsurf.

Even if you configure PATH_BACKEND correctly in the JSON settings, the AI Agent (Client) typically operates inside a Security Sandbox. It often refuses to execute tools or read files that are outside the currently open window/folder to prevent unauthorized access.

The Fix: Multi-Root Workspace To allow the AI to access your external backend folder via MCP, you must explicitly trust it by adding it to your current workspace:

1. Open your Frontend project in the editor.
2. Go to File > Add Folder to Workspace...
3. Select your Backend folder (e.g., /path/to/backend-project).
4. (Optional) Save this setup: File > Save Workspace As...

Result: Both folders are now "inside" the trusted zone. The MCP server will now work correctly without being blocked by the editor's security layer.

---

1. Claude Desktop App (MacOS / Windows)

Claude Desktop is currently the standard implementation for MCP and is less strict about workspace sandboxing than VS Code.

Configuration File Location:

• MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Setup Steps:

1. Open the configuration file in a text editor.
2. Add your server under mcpServers.

{
  "mcpServers": {
    "fullstack-server": {
      "command": "python3",
      "args": [
        "/absolute/path/to/your/repo/server.py"
      ],
      "env": {
        "PATH_FRONTEND": "/absolute/path/to/frontend-project",
        "PATH_BACKEND": "/absolute/path/to/backend-project"
      }
    }
  }
}

Note: If you use a virtual environment (venv), replace "python3" with the path to the python executable inside the venv.

2. Cursor (AI Editor)

Cursor creates a bridge to local scripts via its "Features" settings.

Setup Steps:

1. Open Cursor Settings (Ctrl + , or Cmd + ,).
2. Go to Features -> MCP Servers.
3. Click "Add New Server".
4. Fill in the details:
   • Name: Fullstack Context
   • Type: Command (stdio)
   • Command:

     python3 /absolute/path/to/your/repo/server.py
     

   • Environment Variables:
     • PATH_FRONTEND: /absolute/path/to/frontend-project
     • PATH_BACKEND: /absolute/path/to/backend-project

Crucial Step: Ensure you add both Frontend and Backend folders to the workspace (File > Add Folder to Workspace) so the AI has permission to use the MCP tools on them.

3. VS Code (via Cline / Roo Code)

VS Code Native does not support MCP yet. You must use the Cline (formerly Claude Dev) or Roo Code extension.

Setup Steps:

1. Install Cline from VS Code Marketplace.
2. Open Cline in the sidebar.
3. Click the MCP Server Icon (Database icon) or Settings.
4. Select "Edit MCP Settings".
5. Paste the configuration:

{
  "mcpServers": {
    "fullstack-server": {
      "command": "python",
      "args": ["/absolute/path/to/your/repo/server.py"],
      "env": {
        "PATH_FRONTEND": "/absolute/path/to/frontend-project",
        "PATH_BACKEND": "/absolute/path/to/backend-project",
        "PYTHONUTF8": "1"
      }
    }
  }
}

⚠️ Important: VS Code is very strict. If PATH_BACKEND is outside the current window, you MUST use File > Add Folder to Workspace to include that folder, otherwise Cline will refuse to run the tool or read files from it.

4. Google Gemini CLI (npm)

This section explains how to connect the official npm gemini-cli to this MCP server.

Setup Steps:

1. Install and Authenticate Gemini CLI:

   npm install -g @google/gemini-cli
   gemini configure
   

2. Configure Gemini CLI for MCP: Open the Gemini CLI configuration file. Its location varies by OS:

   • Linux/macOS: ~/.config/@google-gemini-cli/config.json
   • Windows: %APPDATA%\@google-gemini-cli\config.json

   Add your server configuration under the mcpServers section:

{
  "mcpServers": {
    "fullstack-server": {
      "command": "python3",
      "args": [
        "/absolute/path/to/your/repo/server.py"
      ],
      "env": {
        "PATH_FRONTEND": "/absolute/path/to/frontend-project",
        "PATH_BACKEND": "/absolute/path/to/backend-project"
      }
    }
  }
}

Note: Ensure that /absolute/path/to/your/repo/server.py points to the correct location of your MCP server script. Replace /absolute/path/to/frontend-project and /absolute/path/to/backend-project with the actual absolute paths to your frontend and backend project directories, respectively.