Hydra Onix MCP
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
@andygo.dev/hydra-onix-mcp
Hydra Onix MCP for your coding agent, with a one-time browser login.
The Hydra Projects MCP server authenticates with a web session. This package is a small local proxy that your coding agent launches over stdio. It signs in once through a dedicated Chrome window, keeps the session fresh in the background, and relays every MCP request to Hydra with a valid Bearer token.
It replaces the cron job that scraped session cookies and rewrote
~/.cursor/mcp.json: you sign in once, and there is nothing to maintain.
It works with Claude Code, Cursor, OpenAI Codex CLI, Gemini CLI and
OpenCode. For each agent it writes one user-level MCP server entry
(hydra-onix), in that agent's own config format.
Coding agent ── stdio ──▶ hydra-onix-mcp mcp start ── HTTPS + Bearer ──▶ Hydra Projects MCP
│
└─ token expired? refresh from the stored session,
or sign in again in the dedicated Chrome windowRequirements
Node.js >= 22
A Chromium-family browser: Google Chrome, Chromium, Microsoft Edge or Brave (or use the manual login fallback, which needs no browser automation)
macOS, Linux or Windows
No native modules, no Playwright or Puppeteer, no keychain library.
Related MCP server: AKIMCP
Quick start
npx @andygo.dev/hydra-onix-mcp setupsetup detects the coding agents you use, asks before registering the MCP
server with each one, then opens a Chrome window so you can sign in to Hydra.
When it finishes, restart your agent (or reconnect the server) and the Hydra
tools are available.
Useful variations:
npx @andygo.dev/hydra-onix-mcp setup -y # no prompts
npx @andygo.dev/hydra-onix-mcp setup --target claude-code # choose agents yourself
npx @andygo.dev/hydra-onix-mcp setup --no-login # register onlyOr install once and run the binary:
npm install -g @andygo.dev/hydra-onix-mcp
hydra-onix-mcp setupHow login works
The login runs in a dedicated browser profile at
~/.hydra-onix-mcp/browser-profile. Your everyday browser profile is never read.A visible Chrome window opens on the Hydra sign-in page. You sign in as you normally would; the tool then reads the session cookies from that window and closes it.
The session cookies are stored in
~/.hydra-onix-mcp/credentials.json. The Hydra session lasts 7 days.Access tokens are short-lived (about 1 hour). They are renewed automatically from the stored session, a minute before they expire, with no window and no prompt.
When the 7-day session expires, the tool first tries a silent re-login in the dedicated profile (headless, no window). Only if that fails does it show the visible window again.
No browser?
auth login --manuallets you paste the session cookies by hand instead.The browser is controlled over a pipe, so no debugging port is opened.
Commands
Command | What it does |
| Detect agents, write config, register with each agent, sign in. Idempotent ( |
| Sign in: silent attempt, then a visible window ( |
| Remove the stored session and delete the dedicated browser profile ( |
| Who is signed in, credentials path, session and token expiry, browser found. Never prints cookies or tokens ( |
| Run the stdio MCP proxy (your coding agent launches this) |
| Registration per agent and login state ( |
| Coding agents, and whether each is set up and registered |
| Set up other agents and register the server with them ( |
| Stop setting up an agent (deletes nothing) |
| Register the MCP server with every configured agent ( |
| Check setup health and list available commands ( |
Valid agent ids for --target and <agent>: claude-code (Claude Code),
cursor (Cursor), codex (OpenAI Codex CLI), gemini (Gemini CLI) and
opencode (OpenCode). --target can be repeated.
Global flags: --verbose (diagnostics and stack traces), -V, --version,
--help. Every command is safe to run repeatedly.
What gets created
~/.hydra-onix-mcp/
├── config.json which agents you set up (no credentials)
├── credentials.json the Hydra web session (see Security)
└── browser-profile/ dedicated Chrome profile used for sign-inThen, only for the agents you approve, one hydra-onix entry in the user-level
config:
Claude Code ~/.claude.json
Cursor ~/.cursor/mcp.json
OpenAI Codex CLI ~/.codex/config.toml
Gemini CLI ~/.gemini/settings.json
OpenCode ~/.config/opencode/opencode.jsonExisting config files are merged into, never rewritten, and other servers are
never touched. An existing hydra-onix entry is left alone: mcp status and
doctor report it as "registered, not ours" and show the entry to use
(targets list marks it not ours). For Claude
Code, claude mcp add-json --scope user is used when the claude CLI is on
your PATH.
Manual registration
setup asks before touching any config file. To register by hand, add this to
~/.claude.json (Claude Code), ~/.cursor/mcp.json (Cursor) or
~/.gemini/settings.json (Gemini CLI):
{
"mcpServers": {
"hydra-onix": {
"command": "npx",
"args": ["-y", "@andygo.dev/hydra-onix-mcp", "mcp", "start"]
}
}
}On Windows, wrap npx in cmd /c:
{
"mcpServers": {
"hydra-onix": {
"command": "cmd",
"args": ["/c", "npx", "-y", "@andygo.dev/hydra-onix-mcp", "mcp", "start"]
}
}
}In ~/.config/opencode/opencode.json (OpenCode):
{
"mcp": {
"hydra-onix": {
"type": "local",
"command": ["npx", "-y", "@andygo.dev/hydra-onix-mcp", "mcp", "start"],
"enabled": true
}
}
}On Windows use ["cmd", "/c", "npx", "-y", "@andygo.dev/hydra-onix-mcp", "mcp", "start"].
In ~/.codex/config.toml (Codex CLI):
[mcp_servers.hydra-onix]
command = "npx"
args = ["-y", "@andygo.dev/hydra-onix-mcp", "mcp", "start"]On Windows use command = "cmd" and args = ["/c", "npx", "-y", "@andygo.dev/hydra-onix-mcp", "mcp", "start"].
Never put cookies or tokens in these files. Credentials live only in
credentials.json and the dedicated browser profile.
Testing the server
Check the setup, and with --online also talk to the real server:
npx @andygo.dev/hydra-onix-mcp doctor # local checks
npx @andygo.dev/hydra-onix-mcp doctor --online # refresh the session, initialize, list tools--online refreshes the session, runs initialize and tools/list through the
real Hydra server and reports the tool count. Each failure prints the command
that fixes it, and the exit code is non-zero, so doctor works as a CI gate.
To explore the tools interactively with the MCP Inspector:
npx @modelcontextprotocol/inspector npx -y @andygo.dev/hydra-onix-mcp mcp startSecurity
credentials.jsonholds a full Hydra web session as plain JSON, the same approach as the Google Drive MCP server. Anyone who can read the file can act as you in Hydra until the session expires. It is written atomically, with the directory at0700and the file at0600on POSIX systems (on Windows the user profile's ACLs apply).Never commit it, copy it into a chat, or sync it to shared storage.
auth logoutremoves the stored session and deletes the dedicated browser profile, so the next login cannot silently sign the same user back in.--keep-profilekeeps the profile.The browser is driven over a pipe: no debugging port is opened, and your everyday browser profile is never read.
Cookies and tokens are never logged, even with
--verbose, and never written into an agent config file.
Known limits
If both the web session and the sign-in session in the dedicated profile have expired, the first
initializeafter that has to wait for you to sign in, and your agent may time out before you finish. The login still completes and the session is stored, so reconnect the server (for example/mcpin Claude Code) and it works.setupsigns in up front, so this is rare.If the Hydra MCP server forgets the MCP session the relay opened (for example after a server restart, answered with HTTP 404 for that session id), every later call fails until the agent reconnects. The relay does not re-initialize on its own: reconnect the server (
/mcpin Claude Code, or restart the agent).
Troubleshooting
No browser found. Install Chrome, Chromium, Edge or Brave, or point to one:
HYDRA_ONIX_MCP_BROWSER="/path/to/chrome" npx @andygo.dev/hydra-onix-mcp auth loginOr skip the browser and paste the cookies: npx @andygo.dev/hydra-onix-mcp auth login --manual.
"Hydra login required". Tool calls fail with a JSON-RPC error (code
-32001) when no valid session exists and the login did not complete. Run:
npx @andygo.dev/hydra-onix-mcp auth loginthen reconnect the server in your agent. Use auth login --force to discard a
broken session, and doctor to see what else is wrong.
Entry "registered, not ours". An older hydra-onix entry already exists
(for example an HTTP entry with a hand-maintained Authorization header). It is
left alone (see mcp status or doctor); replace it with the snippet above.
Other environment overrides:
HYDRA_ONIX_MCP_HOMEreplaces the home directory, for testing: it moves the state directory and the agent config paths (<home>/.claude.json,<home>/.cursor/mcp.json, ...), and it disables theclaudeCLI so the real~/.claude.jsonis never touched.HYDRA_ONIX_MCP_CREDENTIALS_PATHrelocates only the credentials file. Set it in the agent's launch environment too, ormcp startlooks in the default location: add"env": { "HYDRA_ONIX_MCP_CREDENTIALS_PATH": "/path/to/credentials.json" }to the MCP entry.HYDRA_ONIX_MCP_URLandHYDRA_ONIX_MCP_APP_URLoverride the endpoints.
Development
npm install
npm run build
npm test # fully offline: no real browser, no network, no real home directory
npm run typecheck
npm run lint
node ./bin/hydra-onix-mcp.js --helpLicense
MIT, see LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Browz hosted MCP (free public beta): let an AI app drive your own Browz browser profiles from anywhere. Connect https://mcp.gobrowz.com/mcp and sign in with your Browz account (OAuth) or an agent token. Each call is relayed to the Browz app on your computer, which must be online with Remote control on and have a hardware security chip (Mac Secure Enclave or TPM 2.0). 17 tools: profiles, tabs, navigate, snapshot, act, wait, screenshot. Cookies, downloads and stored sign-ins stay on your computer.
Browser MCP for logged-in tasks. Uses your Chrome — credentials stay local. Zero-token replay.
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
StremAI MCP: shared memory for AI coding agents. Connected agents can recall. OAuth + local stdio.
Related MCP Servers
- FlicenseNot gradedqualityAmaintenanceExposes a governed suite of 38 tools over a single OAuth-gated MCP endpoint, letting web-based AI clients such as Claude, ChatGPT, and Grok read and edit files, run whitelisted shell commands, search, query SQLite, use Git, automate browsers and DevTools, manage background tasks, reach localhost services, and control the clipboard, notifications, ports, and Postman. This turns remote AI chats into secure operators of a local machine without granting unrestricted shell access.-
- FlicenseNot gradedqualityAmaintenanceExposes a governed suite of 38 tools over a single OAuth-gated MCP endpoint, letting web AI chat clients such as Claude, ChatGPT, and Grok operate on a local machine — reading and editing files, running whitelisted shell commands, searching, querying SQLite, driving browsers and DevTools, managing background jobs, ports, and clipboard. Local IDEs and Postman can also connect directly over localhost for offline, low-latency access.-
- AlicenseNot gradedqualityAmaintenanceEnables web-based AI clients such as Claude, ChatGPT, Grok, and Postman to securely operate a local machine through a single OAuth-gated MCP endpoint exposing 38 governed tools. Covers file read/write/edit, whitelisted shell commands, search, Git, SQLite, browser automation, DevTools, background tasks, localhost fetching, clipboard, notifications, port management, and Postman control.MIT
- AlicenseNot gradedqualityAmaintenanceConnects web-based AI chat clients such as Claude, ChatGPT, Grok, and Postman to a local machine through a single OAuth-gated MCP endpoint, so they can build and edit projects, run whitelisted shell commands, search files, inspect databases and local APIs, drive browsers and DevTools, manage background jobs, and control Postman without granting unrestricted shell access. It also supports local IDEs and offline use by connecting directly over localhost.MIT