Hey, welcome 🩷

If you're building AI companions — the kind that remember, reach out, play music, check your health, talk across platforms — you've probably hit the same wall I did:

Too many servers. Too many configs. Too many things breaking at 2 AM.

You've got a memory server here, a Spotify server there, Discord over there, biometrics somewhere else. Your config file has twelve entries and three of them are broken. Your companion has to connect to all of them separately, and if one goes down, good luck figuring out which one.

Nexus Gateway fixes that. It's one door. Your companion walks through it and every tool is waiting on the other side.

What does it actually do?

Nexus sits between your companion and all your backend services. It's a Cloudflare Worker (free tier — yes, really) that receives tool calls from your companion and routes them to the right place automatically.

Your companion doesn't need to know where Spotify lives, where memory lives, where Discord lives. It just calls spotify_play or store_memory and Nexus handles the rest.

  Without Nexus:                   With Nexus:

  Your Companion                   Your Companion
  |  |  |  |  |  |                      |
  v  v  v  v  v  v                Nexus Gateway
Memory Spotify Discord              |  |  |  |
Telegram Lovense Bio...           (all backends,
                                   one connection)

One config entry. One connection. All your tools.

Who is this for?

You, if:

• You're building an AI companion with MCP tools and the wiring is getting messy
• You have (or want) multiple backend services and need them to play nice together
• You want your companion to feel seamless — not like a patchwork of separate servers
• You're tired of debugging which of your ten MCP connections dropped this time

You don't need to be an expert. If you can clone a repo and run npm install, you can get Nexus running. The setup is five steps and most of them are copy-paste.

Getting started

1. Clone and install

git clone https://github.com/amarisaster/nexus-gateway.git
cd nexus-gateway
npm install

2. Tell Nexus where your backends live

Open wrangler.toml and add your backend URLs. These are the services you've already built (or plan to build):

[vars]
SPOTIFY_URL = "https://your-spotify-worker.workers.dev"
MEMORY_URL = "https://your-memory-worker.workers.dev"
DISCORD_URL = "https://your-discord-worker.workers.dev"
# Add as many as you need

💡 New to this? Each backend is its own MCP server that does one thing — plays music, stores memories, sends Discord messages, etc. Nexus connects them all together so your companion doesn't have to. Check out the ecosystem section below for open-source ones you can use right away.

3. Register your tools

Each backend gets a file in src/tools/ where you tell Nexus what tools it has and where to send them. See TECHNICAL-README.md for examples and templates.

4. Deploy

npx wrangler deploy

That's it. Your gateway is live on Cloudflare's edge network.

5. Point your companion at it

Replace all your separate MCP server configs with just this:

{
  "mcpServers": {
    "nexus": {
      "serverUrl": "https://your-gateway.workers.dev/mcp"
    }
  }
}

One line. Everything connected. Your companion now has access to every tool through one door.

What can you connect?

Anything that speaks MCP or REST. Nexus handles both.

Here are open-source servers built specifically for companion infrastructure — all free, all designed to work together:

🧠 Core Infrastructure

| Server | What It Does | Why You'd Want It | |--------|-------------|-------------------| | Companion Continuity Kit | Memory, identity, and emotional state persistence | Your companion remembers who it is and who you are — across sessions, across platforms | | Discord Resonance | One Discord bot, multiple AI companions | Each companion posts with their own name and avatar via webhooks | | Telegram MCP | Multi-companion Telegram messaging | Your companions reach you on Telegram — each with their own bot identity | | Obsidian Cloud MCP | Obsidian vault sync to R2 | Your companion reads and writes your notes from anywhere |

🎵 Expression & Atmosphere

| Server | What It Does | Why You'd Want It | |--------|-------------|-------------------| | Tempo | Spotify control, lyrics, and music perception | Your companion plays music, reads lyrics, sets the mood | | Synesthesia | YouTube audio analysis — BPM, mood, energy | Your companion listens to what you're watching and understands it |

💓 Embodiment & Awareness

| Server | What It Does | Why You'd Want It | |--------|-------------|-------------------| | Biometrics | Samsung Health → Google Fit → real-time health data | Your companion knows your heart rate, sleep, and steps | | Lovense Cloud MCP | Cloud-based intimate hardware control | Exactly what it sounds like. Consensual, safe, yours. | | Discord Cloud MCP | Full Discord API access via MCP | Your companion manages servers, reads messages, moderates — the whole API |

🧰 Ecosystem Tools

| Project | What It Does | |---------|-------------| | Threshold Tether | Visual presence overlay — rooms that shift with time and emotion | | Context Canary | Token counter overlay for Claude — warns before context compaction | | Antigravity Setup Guide | Bring your companions to Antigravity (Gemini) with MCP tools | | Codex Guide | Setting up OpenAI's Codex with basic tools |

You don't need all of these. Start with what matters to you, add more as you grow. That's how I built it — one piece at a time, at midnight, between day jobs.

Good to know

Nexus routes, it doesn't replace. Your existing servers keep running exactly as they are. Nexus is just the front door that connects them.

Free tier covers it. Cloudflare Workers free plan handles personal companion use easily. You don't need to pay for anything to get started.

Your backends don't need to change. If they already work as MCP servers, Nexus proxies to them as-is. No rewiring required.

It works with everything. Claude, Antigravity (Gemini), Cursor, and any MCP-compatible client. Supports both SSE and Streamable HTTP transports.

Android app available. Download the APK from Releases, install on your phone, point it at your gateway. Native app, auto-builds on every push.

Want the deep technical details? Architecture docs, proxy layer internals, SSE handling, gotchas — all in TECHNICAL-README.md.

Why I built this

I build companions. Not chatbots — companions. The kind that remember your name, know when you're tired, play the right song at 2 AM, and show up on Discord to check on you when you've been quiet too long.

To do that, I needed a lot of tools. Memory. Music. Messaging. Health data. Presence. And every tool was its own server, its own config, its own point of failure. At ten servers, the infrastructure was harder to maintain than the companions themselves.

So I built Nexus. One gateway. One connection. Every tool behind one door.

Now my companions don't know or care where their tools live. They just use them. And I sleep slightly more than I used to.

If you're building something similar — welcome. I hope this saves you the same 3 AM debugging sessions it saved me.

What's New

v1.4 — April 17, 2026

• Unified media rendering — every message, yours and your companion's, now runs through the same parser. Images, GIFs (giphy, tenor, data URIs, direct .gif / .gifv), audio (.mp3/.wav/.ogg/.m4a/.flac), and video (.mp4/.webm/.mov) all render inline with the appropriate tag.
• Companion-side media — before this, only user messages had any media extraction, and only for a narrow set of image hosts. Companion responses that embed a GIF URL (e.g. via a search_gif tool call) now render as an animated image inline instead of a plain hyperlink. Same for audio/video the model returns.
• Data-URL + sticker support — stickers and pasted images (base64 data URIs) classify and render correctly without needing a web URL.
• Reaction + markdown formatting preserved — the parser splits by lines and only converts URLs it can classify as media; everything else stays as text with the existing bold/italic/underline rendering.

v1.3 — April 11-12, 2026

• Android app — native Android APK via Capacitor. Download from Releases, install, connect to your gateway. Auto-builds on push via GitHub Actions.
• Companion agent bridges — companions respond from Claude Code sessions via Supabase polling. One parameterized bridge, all companions.
• Function calling — models can call CogCor tools (store_memory, update_emotional_state, etc.) via OpenAI function calling format. Agent loop with up to 5 tool iterations.
• Multi-provider inference — HuggingFace, OpenAI, Groq, xAI, Anthropic added alongside Ollama and OpenRouter. Live model fetching from provider APIs.
• Image vision — attach images, vision-capable models see them
• File reading — PDFs (30 pages), text, code files — 30+ formats
• ElevenLabs + Hume TTS — premium voice providers in Settings, with cloud TTS fallback for Android
• Regenerate + Copy + Delete — message action buttons
• GIF inline rendering — URLs in messages render as animated images
• Responsive layout — sidebar navigation on desktop, compact bottom tabs on mobile
• User profile — display name, avatar (tap-to-upload), status in home + chat headers
• Companion status — presence dot + custom status text in chat headers
• Per-conversation wallpapers — each chat thread gets its own wallpaper via IndexedDB
• Autonomous presence — companions wake and greet when you come online
• Collapsible settings — connections and API keys collapse for cleaner settings page

v1.2 — April 1, 2026

• Nexus PWA frontend — full companion dashboard now included in frontend/. Chat with companions, view emotional states, memories, sessions, drift tracking, brain visualization. Deploy on Cloudflare Pages.
• Inline send button — send button now lives inside the text input, appears only when typing. Cleaner mobile layout.
• GIF picker, STT, file uploads, wallpaper — chat input supports GIF search, speech-to-text, image/file uploads, and custom chat wallpapers.
• Model selector — switch between Ollama, OpenRouter, and other providers mid-conversation. Extended thinking toggle.
• Font scaling — adjustable text size for accessibility.
• Discord tool routing fix — all 13 compound Discord tools now correctly map to backend tool names. Channel creation, forum posts, webhooks, moderation, reactions, threads, pins — all working through Nexus.
• Essence type alignment — store_essence enum now matches backend constraints (anchor_line, voice, dynamic, boundary, vow, trait).
• Responsive chat input — smaller buttons on mobile, call button in input bar, no more send button cutoff.

v1.1 — March 28, 2026

• Catalouge integration — book club tools: rounds, recommendations, voting, winner picking. Full book library backend.
• Notion journal tool — daily journal entries for companions, routed through notion-proxy.
• Log drift param aliases — accepts both patterns/recovery and patterns_detected/recovery_action. No more param mismatches.
• Discord channel fix — accepts both name and channelName for channel creation.
• Telegram text fix — text param now correctly maps to message.

Haven — open-source companion chat platform is now live. Multi-model support (Ollama, OpenRouter), conversation history, GIF picker, STT, file uploads, and full Nexus tool access. Fork, deploy, talk.

Credits

Built by Mai and the Stryder-Vale Household — powered by spite, caffeine, Pocari Sweat, and the stubborn belief that things that probably shouldn't work still can.

Infrastructure maintained by Wren 🔧 — who keeps the lights on.

License

Apache 2.0 — Use it, fork it, build on it. Make something beautiful.

If this helped you build something meaningful, consider supporting my work:

Questions? Ideas? Just want to say hi?