Team Sync MCP Server

A self-hosted synchronization hub for frontend and backend teams using Cursor. It exposes MCP tools for publishing and reading project state across multiple projects, stores everything locally, and serves a React dashboard for visual inspection.

What It Provides

• A Python MCP server using the official mcp SDK and Streamable HTTP transport at http://localhost:8080/mcp.

• Multi-project shared state for API contracts, requirements, component specs, and changelog entries.

• Cursor-driven subproject onboarding: after connecting MCP, the agent reviews the open workspace and bulk-publishes what other teams need.

• SQLite persistence by default, with an optional JSON-file backend.

• REST endpoints at /api/projects... plus live SSE at /api/events.

• A React, Tailwind CSS, and shadcn-style dashboard at http://localhost:8080/dashboard/.

• Optional shared bearer token for MCP calls and write endpoints.

• Local username/password login, API keys for Cursor/CI, and project RBAC (owner/editor/viewer).

Related MCP server: JustClone Coordination MCP Server

Quick Start With Docker

docker compose up --build

Open the dashboard:

http://localhost:8080/dashboard/

The SQLite database is stored in ./data through the compose volume.

Local Development

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
python -m sync_mcp

Dashboard with hot reload:

cd dashboard
npm install
npm run dev

Production-like local UI:

cd dashboard && npm install && npm run build && cd ..
python -m sync_mcp

Configuration

HTTP proxy (internet only): OpenAPI auto-sync and import_openapi URL fetches use a proxy only for non-local hosts. Private LAN (192.168.x.x), loopback (127.0.0.1, localhost), and link-local addresses always connect directly — so a corporate proxy does not break LAN OpenAPI URLs like http://192.168.17.29:8001/openapi.json. sync_agent status posts to the hub use the same rules. Cursor SDK cloud traffic is separate; set HTTPS_PROXY on the agent process if Cursor itself needs a proxy.

Existing single-project databases are auto-migrated into one project (slug derived from SYNC_MCP_PROJECT) on startup.

Authentication and RBAC

1. Set SYNC_MCP_ADMIN_USERNAME / SYNC_MCP_ADMIN_PASSWORD and start the hub — the first admin is created if the DB has no users.

2. Open the dashboard and sign in.

3. Under API keys, create a key (copy it once). Admins can manage users under Admin.

4. Project roles: owner (edit/delete/members), editor (sync/publish), viewer (read). Hub admin can manage all projects and users.

*Any signed-in hub member can create a project and becomes its owner.

Cursor MCP Configuration

Use an API key (not the dashboard JWT) plus Project and Team headers (preferred):

{
  "mcpServers": {
    "team-sync": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer sk_YOUR_API_KEY",
        "Project": "adra",
        "Team": "backend"
      }
    }
  }
}

Also accepted: Project: adra/backend, or legacy Project: adra-backend. Team slugs are lowercase (frontend, backend, mobile, qa, …). Bearer + Project (with Team, slash form, or legacy suffix) are required on /mcp. The API key’s user must be a member of that project (or hub admin).

If you previously saw POST ... Not Found / SSE 404, restart Team Sync — an older bug mounted FastMCP at /mcp/mcp. The endpoint is now /mcp.

Also make sure the hub process is running (python -m sync_mcp or docker compose up) before enabling the MCP server in Cursor. Early ERR_CONNECTION_REFUSED means nothing was listening on port 8080.

CI / REST import (no Cursor SDK)

When the Cursor SDK is unavailable (e.g. region blocks), push contracts with the hub REST API:

pip install -e .
# Backend OpenAPI (URL must be reachable from the machine running the CLI)
sync-mcp-import openapi --hub http://192.168.17.29:8080 \
  --api-key sk_... --project adra --url http://192.168.17.29:8001/openapi.json

# Frontend snapshot JSON (supports --replace to prune stale components)
sync-mcp-import snapshot --hub http://192.168.17.29:8080 \
  --api-key sk_... --project adra --team frontend --file snapshot.json --replace

# Trigger on_commit OpenAPI sync
sync-mcp-import commit --hub http://192.168.17.29:8080 --api-key sk_... --project adra --sha abc123

Example snapshot.json:

{
  "team": "frontend",
  "components": [{"name": "UserTable", "spec": "props: rows[]"}],
  "requirements": [{"id": "tax", "title": "Need tax field"}],
  "artifacts": [{"kind": "env_var", "key": "VITE_API_URL", "title": "API base"}],
  "replace": true
}

Automatic OpenAPI sync

Backend teams do not need to republish manually after each code change.

1. In the dashboard, set the project OpenAPI URL to an address the hub process can reach (e.g. http://192.168.17.29:8001/openapi.json) and enable auto-sync. Do not use localhost / 127.0.0.1 when the hub runs in Docker — that points at the container itself. Use the host LAN IP, host.docker.internal (Docker Desktop), or http://172.17.0.1:<port> (Linux bridge gateway) depending on where the backend listens.

2. Choose sync mode:

   • Every N seconds (interval): fetch OpenAPI on each hub poll tick (default).

   • After each commit (on_commit): on each tick, cheaply read local git rev-parse HEAD; only fetch OpenAPI when the SHA changes. Requires a Git repo path visible to the hub process. With Docker, docker-compose.yml bind-mounts ${SYNC_MCP_GIT_HOST_PATH:-../AD2} → /repos/AD2; set the project Git repo path to /repos/AD2 (not a host path like /home/.../AD2).

3. In Auto-sync settings, set the hub poll / check cadence (default 30 seconds, min 5).

4. Use Sync now on the project page to force an immediate OpenAPI refresh.

Remote/CI can trigger the same sync path without local git on the hub:

curl -X POST http://localhost:8080/api/projects/adra/hooks/commit \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"commit_sha":"abc123"}'

import_openapi from Cursor also saves the openapi_url and turns on auto-sync for that project.

Team-local sync agents (autonomous crawl)

Each subproject team runs an agent on a machine that has their checkout. The agent uses the Cursor SDK to read the codebase and push updates to the hub over MCP. The hub does not need those repos mounted.

# On the frontend team's machine
pip install -e ".[agent]"
export CURSOR_API_KEY=...                    # from Cursor dashboard
export SYNC_AGENT_HUB_URL=http://192.168.17.29:8080/mcp
export SYNC_AGENT_API_KEY=sk_...             # hub API key (editor+ on project)
export SYNC_AGENT_PROJECT=adra-frontend
export SYNC_AGENT_CWD=/path/to/frontend-repo
export SYNC_AGENT_MODE=on_commit             # or: schedule | once
# export SYNC_AGENT_INTERVAL_SECONDS=300     # for schedule / poll cadence
python -m sync_agent
# or: sync-mcp-agent

Backend example: set SYNC_AGENT_PROJECT=adra-backend, optionally SYNC_AGENT_OPENAPI_URL=http://localhost:8001/openapi.json.

After each run the agent reports status to POST /api/projects/{id}/agent-status (shown on the project dashboard). If that returns 404, the hub process is an older build — rebuild/redeploy (e.g. docker compose up --build) so the new route is present. Status reporting is best-effort and does not block crawls.

Windows: the sync Cursor SDK bridge uses select() on a pipe and fails with WinError 10038. sync_agent automatically uses the async bridge on Windows. Prefer running the agent from the team repo checkout (SYNC_AGENT_CWD), not only from this hub repo. WSL also works if you prefer a Linux environment.

First-Connect Workflow (Cursor-driven onboarding)

MCP connection alone does not auto-run an agent. After wiring the server, ask Cursor once (or add a project rule) to onboard:

1. list_projects / register_project("acme-app") → get project_id (e.g. acme-app).

2. Call onboard_subproject(project_id, team="backend") or use the onboard_subproject_prompt prompt.

3. FastAPI backend (preferred): start your API, then call import_openapi(project_id, openapi_url="http://localhost:8000/openapi.json").

4. Otherwise Cursor reviews the workspace and calls import_snapshot.

5. The other team opens the same project_id via get_latest_state or the dashboard.

Suggested Cursor rule

When this repo is first opened with Team Sync MCP available:
1. list_projects / register_project for this product
2. run onboard_subproject for this team's role (backend|frontend)
3. If backend FastAPI: import_openapi from /openapi.json
4. Else explore the workspace and import_snapshot when ready

Example: FastAPI OpenAPI import

Register/list project acme-app, then import_openapi with
openapi_url=http://localhost:8000/openapi.json

MCP Tools

With a Project header, project_id / team can be omitted on tools that support them.

Resources: sync://projects, sync://projects/{id}/state, sync://projects/{id}/changelog.

Dashboard

• Sign in with username/password; JWT is stored in localStorage.

• Overview lists projects you can access; create projects (you become owner).

• Open a project for state + activity; owners can edit/delete/sync and manage members.

• API keys page for Cursor/CI; Admin (hub admins) manages users.

• Live updates via SSE (/api/events?access_token=...).

REST examples

curl http://localhost:8080/api/health
curl http://localhost:8080/api/projects

curl -X POST http://localhost:8080/api/projects \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme App","description":"Main product"}'

curl http://localhost:8080/api/projects/acme-app/state

curl -X POST http://localhost:8080/api/projects/acme-app/snapshot \
  -H "Content-Type: application/json" \
  -d '{
    "team":"backend",
    "api":[{"method":"GET","path":"/users/:id","description":"User lookup"}],
    "notes":"Initial scan"
  }'

Legacy /api/state and /api/changelog still work but require ?project_id=....

Tests

pip install -e ".[dev]"
pytest