Connect with Cursor and Codex
Add Hilbana as an MCP server in Cursor and Codex with an API key, and work your issues from the editor or the terminal.
Cursor and Codex talk to Hilbana through its MCP server (https://app.hilbana.com/mcp).
They connect with an API key: you create it once and paste it into the client. After
that, the agent lists, creates and closes issues, reads docs and saves project memory, just
like from Claude.
Before you start: create an API key
- In Hilbana, open Settings → Agents → API keys (admins only).
- Create a key. You can make it read-only or limit it to one project.
- Copy it: it starts with
hil_and is shown only once.
Settings → Agents shows these same commands with your instance’s URL already filled in; you only need to swap the sample key for yours.
Cursor
-
Open
~/.cursor/mcp.json(all your projects) or.cursor/mcp.jsonat the root of a project (that project only). Create it if it doesn’t exist. -
Add Hilbana inside
mcpServers:{ "mcpServers": { "hilbana": { "url": "https://app.hilbana.com/mcp", "headers": { "Authorization": "Bearer hil_your_key" } } } } -
Open Cursor’s MCP settings: Settings → Tools & MCP, or Customize in the sidebar in newer versions. Hilbana should show as enabled with its tools. If it doesn’t, restart Cursor.
To keep the key out of the file, use "Bearer ${env:HILBANA_API_KEY}" and define that
environment variable before opening Cursor.
Codex
-
In your terminal, store the key in an environment variable and register the server:
export HILBANA_API_KEY=hil_your_key codex mcp add hilbana --url https://app.hilbana.com/mcp \ --bearer-token-env-var HILBANA_API_KEY -
Check that it is registered:
codex mcp listhilbanashould show asenabledwithBearer tokenauth.
Codex stores the server in ~/.codex/config.toml and reads the key from the variable, so
the key is never written to the file. Start Codex from the same terminal, or keep the
variable in your shell profile, so it can see it.
Try it
Ask the agent, in plain language:
- “List my Hilbana projects.”
- “Get the next agent-ready issue and start on it.”
If it answers with your projects, you’re connected.
Revoking access
Revoke the key in Settings → Agents → API keys: the client loses access immediately. To reconnect, create another key and swap it in the client.
If you’d rather not handle keys, Claude connects with your account through the browser.