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

  1. In Hilbana, open Settings → Agents → API keys (admins only).
  2. Create a key. You can make it read-only or limit it to one project.
  3. 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

  1. Open ~/.cursor/mcp.json (all your projects) or .cursor/mcp.json at the root of a project (that project only). Create it if it doesn’t exist.

  2. Add Hilbana inside mcpServers:

    {
      "mcpServers": {
        "hilbana": {
          "url": "https://app.hilbana.com/mcp",
          "headers": { "Authorization": "Bearer hil_your_key" }
        }
      }
    }
  3. 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

  1. 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
  2. Check that it is registered:

    codex mcp list

    hilbana should show as enabled with Bearer token auth.

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.