# Homelab MCP Bridge

> Fixes and validates Homelab MCP IDE setup when npm client bridges are unavailable. Use when users mention setup-forge-space-mcp, @forge-mcp-gateway/client resolution failures, Cursor/Windsurf MCP config issues, or wrapper bridge migration. Use when this capability is needed.

- Skill: `tomevault-io/homelab-mcp-bridge` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/homelab-mcp-bridge`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/homelab-mcp-bridge/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/homelab-mcp-bridge

---


# Homelab MCP Bridge

## Goal

Standardize MCP IDE setup on the local wrapper bridge (`scripts/mcp-wrapper.sh`) without relying on
`@forge-mcp-gateway/client` npm resolution.

## Workflow

1. Confirm bridge availability:
   - `test -x scripts/mcp-wrapper.sh`
   - `test -s data/.mcp-client-url`
2. Run setup:
   - `./scripts/setup-forge-space-mcp.sh`
3. Validate setup:
   - `python3 scripts/ide-setup.py setup cursor --action verify`
4. If validation fails, emit deterministic fixes:
   - Gateway health failure: `make start`
   - Missing URL file: `make register`
   - Missing wrapper: `chmod +x scripts/mcp-wrapper.sh`
   - Timeout: `CURSOR_MCP_TIMEOUT_MS=180000 ./scripts/setup-forge-space-mcp.sh`
   - If register reports `GET /servers returned 404`: gateway is in minimal mode; switch to a
     deployment profile that exposes `/servers` or set `MCP_CLIENT_SERVER_URL` explicitly in IDE
     config until full mode is available.

## Output Contract

Always report:
- Whether wrapper bridge is configured in IDE config
- Whether `data/.mcp-client-url` exists and matches `/servers/<uuid>/mcp`
- The exact remediation command if any check fails

## Guardrails

- Do not suggest `npx -y @forge-mcp-gateway/client` as an active setup path.
- Keep secrets out of committed files; rely on `.env` and runtime environment variables.
- Preserve existing unrelated `mcpServers` entries while updating bridge config.

---
> Source: [Forge-Space/mcp-gateway](https://github.com/Forge-Space/mcp-gateway) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-16 -->