AI-Context-Sync-MCP — Model Context Protocol Server

This is the Model Context Protocol (MCP) server for AI-Context-Sync-MCP. It runs as an MCP tool provider inside compatible IDE clients (like Claude Desktop, Cursor, and Windsurf) enabling your AI agents to seamlessly push (save) and pull (semantically retrieve) development context, explanations, and codebase summaries.

🔑 How to Get an API Key & Subscription

🚀 Official Hosted Cloud Server Coming in a Few Days! The public cloud registration portal and official hosted API key manager are launching very soon. In the meantime, you can obtain your API key by running the project locally on your machine or self-hosting the backend.

The MCP server requires a valid user API key to authorize sync requests with the backend.

1. Run the Dashboard Console locally:
   • Clone the project repository and run the run-local.bat script in the root directory. This automatically compiles the MCP server and starts the backend (port 8000) and the web dashboard (port 5173).
   • If you have self-hosted the backend on a server (e.g. Railway, Render, etc.), navigate to your custom dashboard URL.
2. Register/Login:
   • Open your browser to http://localhost:5173 (or your hosted dashboard URL), go to the Sign Up tab, and register a new user account.
3. Copy Your API Key:
   • Once logged in, open the Dashboard Console -> Settings / API Key Manager tab.
   • Copy your unique API Key (starts with ctx_).
4. Subscription Tier Management:
   • By default, new accounts are created on the FREE tier (limited to 2 projects, 3 contexts per project, and 20KB context size).
   • In the Subscription Settings section of the Settings tab, you can click the Upgrade to PRO button to simulate upgrading your account to the PRO tier, which unlocks unlimited sync projects and context limits. (Stripe self-checkout registration is coming in a few days along with the hosted portal).

🚀 Installation & Configuration

1. Claude Desktop

Add the following configuration to your claude_desktop_config.json settings file:

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

{
  "mcpServers": {
    "ai-context-sync-mcp": {
      "command": "npx",
      "args": ["-y", "ai-context-sync-mcp"],
      "env": {
        "CONTEXT_SYNC_API_KEY": "YOUR_API_KEY_HERE",
        "CONTEXT_SYNC_BACKEND_URL": "http://127.0.0.1:8000"
      }
    }
  }
}

💡 Replace YOUR_API_KEY_HERE with your ctx_... API key. If your FastAPI backend is running on a custom port or hosted domain (e.g. on Railway), update CONTEXT_SYNC_BACKEND_URL accordingly.

2. Cursor IDE

1. Navigate to Cursor Settings -> Features -> MCP.
2. Click + Add New MCP Server.
3. Fill in the following details:
   • Name: ai-context-sync-mcp
   • Type: command
   • Command:
     • Windows:

       cmd /c "set CONTEXT_SYNC_API_KEY=YOUR_API_KEY_HERE&& set CONTEXT_SYNC_BACKEND_URL=http://localhost:8000&& npx -y ai-context-sync-mcp"

     • macOS / Linux:

       CONTEXT_SYNC_API_KEY=YOUR_API_KEY_HERE CONTEXT_SYNC_BACKEND_URL=http://localhost:8000 npx -y ai-context-sync-mcp

3. Windsurf IDE

1. Open your Windsurf MCP Configuration file located at:
   • Windows/macOS/Linux: ~/.codeium/windsurf/mcp_config.json
2. Add the server entry into the mcpServers object:

   {
     "mcpServers": {
       "ai-context-sync-mcp": {
         "command": "npx",
         "args": ["-y", "ai-context-sync-mcp"],
         "env": {
           "CONTEXT_SYNC_API_KEY": "YOUR_API_KEY_HERE",
           "CONTEXT_SYNC_BACKEND_URL": "http://127.0.0.1:8000"
         }
       }
     }
   }

3. Alternatively, you can configure it via the Windsurf UI panel.

4. VS Code (Cline, Roo Code, and Custom Extension Agents)

For VS Code extensions that support standard MCP servers:

1. Open the global MCP settings configuration file:
   • Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
   • macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
2. Add the configuration entry:

   {
     "mcpServers": {
       "ai-context-sync-mcp": {
         "command": "npx",
         "args": ["-y", "ai-context-sync-mcp"],
         "env": {
           "CONTEXT_SYNC_API_KEY": "YOUR_API_KEY_HERE",
           "CONTEXT_SYNC_BACKEND_URL": "http://127.0.0.1:8000"
         }
       }
     }
   }

5. Antigravity & Agentic Frameworks

Because ai-context-sync-mcp adheres to the open Model Context Protocol spec over stdio transport, it is natively supported by agent platforms (like Antigravity and other dev agents). You can run it dynamically with:

• Command: npx -y ai-context-sync-mcp
• Environment:
  • CONTEXT_SYNC_API_KEY: YOUR_API_KEY_HERE
  • CONTEXT_SYNC_BACKEND_URL: http://127.0.0.1:8000

🛠️ Provided Tools

Once configured, your LLM agent will have access to the following tools:

1. push_context

Saves your current chat summaries, file snippets, or codebase structures directly to the cloud backend.

• Parameters:
  • contextData (required): The actual code context, chat history, or serialized message transcripts to save.
  • projectName (optional): The name of the project this context belongs to (defaults to your active workspace folder name).
  • contextName (optional): A short descriptive name for this context block (e.g., auth-logic).
  • contextDescription (optional): A detailed explanation helping semantic search find this block later.
  • contextType (optional): full, summary, or feature.

2. pull_context

Performs an AI semantic search (powered by Google Gemini 1.5 Flash) on your saved contexts to pull relevant information back into the LLM's active memory context.

• Parameters:
  • searchQuery (required): What you need to retrieve (e.g., "how did we setup JWT authentication?").
  • projectName (optional): Restricts the query to a specific project.