{"id":"99740b52-2a65-4679-adce-d54eb45b5e80","slug":"ha-connector","kind":"mcp","name":"ha-connector","summary":"HostAfrica Connector: registers the HostAfrica remote MCP server with AI editors, CLI agents and chat apps (OAuth-first)","owner":"hostafrica-dev","repoUrl":"https://github.com/hostafrica-dev/ha-connector","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-08-26T18:03:05.000Z","addedAt":"2026-10-21T06:40:03.964Z","logoUrl":"https://avatars.githubusercontent.com/u/286889722?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["communication","cloud-infra","memory-knowledge"],"tags":["claude","dns","hosting","vps","vscode-extension"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-28T01:32:11.720Z","sample":false,"url":"https://conduits.dev/tools/ha-connector","language":"TypeScript","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# HostAfrica Connector\n\n![release](https://img.shields.io/github/v/release/hostafrica-dev/ha-connector?label=release&color=2e3388) ![license](https://img.shields.io/badge/license-MIT-109235) ![MCP](https://img.shields.io/badge/protocol-MCP-555)\n\nRegister the HostAfrica remote MCP server with your AI tools (editors, CLI agents, chat apps), so your assistant can manage VPS servers, DNS, domains, backups and orders from plain-language prompts.\n\nNothing runs locally. The MCP server is HostAfrica's hosted endpoint (`https://mcp.hostafrica.com/mcp`), so connecting a tool means writing one entry into that tool's config. This repo automates exactly that, three ways:\n\n| Vehicle | For |\n|---|---|\n| CLI installer ([`packages/cli`](packages/cli)) | Any machine, any terminal: `hostafrica-connect install` detects your AI tools and registers them all |\n| VS Code extension ([`packages/vscode-extension`](packages/vscode-extension)) | VS Code natively, plus a sidebar that registers every other detected tool; also serves Cursor/Windsurf/Antigravity/Devin users via Open VSX |\n| Registrar core ([`packages/core`](packages/core)) | The shared library both wrap: client detection, config read/merge/write, OAuth/token modes |\n\n## Install\n\nThe extension is on [Open VSX](https://open-vsx.org/extension/hostafrica/connector), the registry Cursor, Windsurf, Antigravity and VSCodium read from. Search for **HostAfrica Connector** in the extensions view and install it there.\n\nFor VS Code, and anywhere not wired to Open VSX, download the `.vsix` from the [latest release](https://github.com/hostafrica-dev/ha-connector/releases/latest):\n\n```bash\ncode --install-extension connector-1.0.3.vsix\n```\n\nSwap `code` for `cursor` or `windsurf` to install into those. VS Marketplace publishing is still to come.\n\nFor terminals and CLI agents, install the CLI from npm:\n\n```bash\nnpm install -g @hostafrica/connect\n```\n\n## Connect your platform\n\nEvery row was verified against the platform's current docs or source (Aug 2026). \"Installer\" means the CLI (`hostafrica-connect install <id>`) or the extension's sidebar; both write the same config.\n\n| Platform | How to connect | Sign-in |\n|---|---|---|\n| Claude Code | Installer (`claude-code`), or manually: `claude mcp add --scope user --transport http hostafrica https://mcp.hostafrica.com/mcp` | Browser OAuth via `/mcp` in-session, or `claude mcp login hostafrica` for headless |\n| Claude Desktop | Two ways, [see below](#claude-desktop-two-ways) | Browser OAuth |\n| claude.ai / mobile / Cowork | Settings → Connectors → *Add custom connector* → paste `https://mcp.hostafrica.com/mcp` | Browser OAuth (the Free plan allows one custom connector) |\n| ChatGPT | Add as a remote MCP connector (see the [developer docs](https://www.hostafrica.com/developers/)) | Browser OAuth |\n| Cursor | Installer (`cursor`), the one-click install deeplink, or edit `~/.cursor/mcp.json` | Browser OAuth (Cursor 1.0+) |\n| VS Code (Copilot) | Install the extension; it registers the server natively (VS Code 1.101+) | Browser OAuth, driven by VS Code |\n| Windsurf | Installer (`windsurf`) writes `~/.codeium/windsurf/mcp_config.json`; then Refresh in the MCP panel | Browser OAuth |\n| OpenAI Codex CLI | Installer (`codex`) writes `~/.codex/config.toml`, or `codex mcp add hostafrica --url https://mcp.hostafrica.com/mcp` | `codex mcp login hostafrica` |\n| Gemini CLI | Installer (`gemini-cli`) writes `~/.gemini/settings.json` | Browser OAuth; `/mcp auth` in-CLI |\n| Google Antigravity | Installer (`antigravity`) writes `~/.gemini/config/mcp_config.json` | Browser OAuth |\n| Devin CLI | Installer (`devin-cli`) writes `~/.config/devin/mcp_config.json` | `devin mcp login hostafrica` |\n| Devin (cloud) | Settings → Connections → MCP servers (org admins) | OAuth or auth header |\n| JetBrains Junie | Installer (`junie`) writes `~/.junie/mcp/mcp.json` | Browser OAuth (\"Authorize\") |\n| JetBrains AI Assistant | Settings → Tools → AI Assistant → MCP → paste `{\"mcpServers\": {\"hostafrica\": {\"url\": \"https://api.hostafrica.com/mcp\", \"headers\": {\"Authorization\": \"Bearer <token>\"}}}}` (2025.3+; no OAuth flow in this UI) | API token |\n| Zed | Add to `context_servers` in settings.json: `{\"url\": \"https://mcp.hostafrica.com/mcp\"}` (installer support planned) | Browser OAuth |\n| Anything stdio-only | `npx mcp-remote https://mcp.hostafrica.com/mcp` as a stdio bridge | Browser OAuth |\n\n### CLI usage\n\n```bash\nhostafrica-connect status                 # what's installed, what's registered\nhostafrica-connect install                # register with everything detected\nhostafrica-connect install cursor codex   # or pick specific clients\nhostafrica-connect uninstall              # remove all registrations\n```\n\n### Claude Desktop, two ways\n\nClaude Desktop can connect to a remote MCP server in two different ways, and they are not the same. Pick one.\n\n**1. Native custom connector (recommended).** In Claude Desktop: Settings → Connectors → *Add custom connector* → paste `https://mcp.hostafrica.com/mcp`. This is the cleanest path: no extra software, Claude signs you in through the browser, and the connection is managed in the app. It works on Free (one custom connector), Pro, Max, Team and Enterprise. Nothing to install, and the CLI is not involved.\n\n**2. CLI installer / `mcp-remote` bridge.** `hostafrica-connect install claude-desktop` writes an entry into `claude_desktop_config.json` that launches `npx mcp-remote` as a local stdio process, which then talks to the remote server for Claude. Use this if you would rather manage the connection from a config file, or the native connector is not available to you. Two things to know:\n\n- It needs **Node.js installed**, because it runs `npx mcp-remote`. The native path does not.\n- The config file entry is stdio, not a remote URL, because Claude Desktop's config file only accepts stdio servers. That is why the bridge exists at all.\n\nBoth end up at the same place (browser OAuth to your HostAfrica account); the native connector is just less moving parts. If you are not sure, use option 1.\n\n## What you can do once connected\n\nAsk your assistant things like:\n\n- *List my VPS servers* / *Reboot web-01* / *Create a snapshot before I deploy*\n- *Add an A record for app.mydomain.co.za pointing at 102.0.0.10*\n- *Is mydomain.africa available? Suggest alternatives*\n- *Set up a weekly backup schedule for db-01*\n- *Show my open orders and retry the failed payment*\n\n~72 tools are live: VPS lifecycle, backups/snapshots, firewall, rDNS, power tasks, monitoring, DNS/DNSSEC, domains, catalogue/orders/payments.\n\n## Authentication\n\nRegistrations point at the OAuth endpoint with no credentials. Your tool opens the browser and you sign in to HostAfrica; grants are scoped to your account and revocable in the [Client Area](https://panel.hostafrica.com/). The endpoint supports Dynamic Client Registration, PKCE and refresh tokens, so every platform above can run the flow itself.\n\nFor the rare case OAuth can't run (JetBrains AI Assistant, CI), generate an API token in the Client Area and pass `--token <token>` or set `HOSTAFRICA_API_TOKEN`. Registrations then use the Bearer endpoint (`https://api.hostafrica.com/mcp`). Tokens written into third-party config files are plaintext by necessity. The connector restricts them to your user account: mode 600 on macOS and Linux, and an explicit NTFS ACL granting only your account on Windows (POSIX mode bits have no effect there). The VS Code extension keeps its own copy in encrypted SecretStorage.\n\n## Try it from source\n\nUntil the packages are published, everything runs from this repo. One-time setup:\n\n```bash\nnpm install\nnpm run build\n```\n\n`npm install` resolves the workspace: external dependencies land in the root `node_modules/`, and the three local packages are symlinked into it so the CLI and extension resolve `@hostafrica/connector-core` to `packages/core` rather than npm. `npm run build` compiles core, then cli, then the extension, in that order; the extension is bundled with esbuild (core baked in) so the `.vsix` doesn't depend on the workspace symlink.\n\n### CLI\n\nRun in place, or link it onto your PATH:\n\n```bash\nnode packages/cli/dist/index.js status\n```\n\n```bash\nnpm link --workspace packages/cli   # then: hostafrica-connect status\n```\n\n```bash\nhostafrica-connect install claude-code cursor   # no args = all detected clients\n```\n\n`install` and `uninstall` write your real tool configs (`~/.cursor/mcp.json`, `~/.codex/config.toml`, and so on); run `status` first to see what would be touched. No token is needed: after installing, each tool asks you to sign in via the browser on first use. In Claude Code run `/mcp` (or `claude mcp login hostafrica` headless), in Codex `codex mcp login hostafrica`; Cursor, Windsurf and Gemini CLI prompt by themselves.\n\n### VS Code extension\n\nQuick dev run: open this folder in VS Code and press F5 (\"Run HostAfrica Connector Extension\"). An Extension Development Host opens with the HostAfrica icon in the activity bar; verify the native MCP registration with the \"MCP: List Servers\" command (VS Code 1.101+).\n\nPackage your own `.vsix` (or just grab the one from the [latest release](https://github.com/hostafrica-dev/ha-connector/releases/latest)):\n\n```bash\ncd packages/vscode-extension && npm run package\n```\n\n```bash\ncode --install-extension packages/vscode-extension/connector-1.0.3.vsix\n```\n\nCursor and Windsurf accept the same flag; swap `code` for `cursor` or `windsurf`.\n\n### Tests\n\n```bash\nnpm test   # unit suites for the registrar core and the CLI (node:test)\n```\n\n```bash\nnpm run test:vscode --workspace packages/vscode-extension   # integration tests: downloads a real VS Code, opens a window briefly\n```\n\n## Contributing\n\nIssues and pull requests are welcome. A good first step is running `npm install && npm run build && npm test` to confirm the toolchain works. Adding a new AI client is usually one small adapter in [`packages/core/src/clients`](packages/core/src/clients) plus a test.\n\n## Security\n\nThe connector only ever writes a server URL, and (in the token fallback) an API token, into your local tool configs. It never sends your token anywhere except the HostAfrica MCP endpoint you signed in to. Found a security issue? Please report it privately through this repo's Security tab (GitHub private vulnerability reporting) rather than opening a public issue.\n\n## License\n\n[MIT](LICENSE) © HostAfrica\n"}