API & MCP

Hilbana exposes the same database two ways: a product REST API and an MCP (Model Context Protocol) server, so an AI client can operate the tracker with tools.

API keys

Managed in Settings → API keys (admins only). Each key:

• Has the format hil_… and is shown in full only once when created (afterwards you only see its prefix).
• Has a scope: the whole workspace or a specific project. Without a project, the key also reaches every other workspace its owner belongs to (see below); scoped to a project, it does not.
• Can be read-only.
• Can be revoked at any time.

The MCP endpoint

The MCP server lives at https://app.hilbana.com/mcp. To connect a client like Claude Code:

claude mcp add --transport http hilbana https://app.hilbana.com/mcp \
  --header "Authorization: Bearer hil_xxxxxxxx_..."

Config file setup

If your client is configured with a JSON file (.mcp.json at the project root, claude_desktop_config.json, your editor’s mcp.json…), here’s the equivalent entry. Copy it and swap in your own key:

{
  "mcpServers": {
    "hilbana": {
      "type": "http",
      "url": "https://app.hilbana.com/mcp",
      "headers": {
        "Authorization": "Bearer hil_xxxxxxxx_..."
      }
    }
  }
}

If your client supports OAuth, drop the headers block: it will ask you to log in through the browser the first time, and you won’t have keys sitting in a file.

Authentication

Two ways, side by side:

• API key: paste the Bearer hil_…. The scope and read-only mode come from the key itself. Recommended for agents and services (and for headless / CI setups).
• OAuth 2.1 with Dynamic Client Registration (DCR): browser login, with no keys to manage by hand, for MCP clients that support it. Write permissions depend on the granted scope.

One connection, many workspaces

A key identifies the person who created it, not a workspace. The connection reaches every workspace that person belongs to, and the workspace where the key was created is simply the default: the one used when a call doesn’t say otherwise.

In practice: if someone invites you to another workspace, you don’t have to do anything. Your existing MCP client already reaches it — no need to ask its admin for a key, and no second server to register.

How the agent aims:

• list_workspaces lists the ones within reach and marks which is the default.
• Tools that take an entity id (get_issue, add_comment, change_issue_state…) infer the workspace from that entity: nothing to pass.
• Listing tools (list_issues, list_projects, search_issues…) take an optional workspaceId. Without it they use the default, so existing sessions and setups behave exactly as before.
• Creation tools answer with the workspace the new thing ended up in.
• An identifier like ABC-123 is no longer unique across workspaces: a search by identifier may return several matches, each with its workspace.

Two things worth knowing up front:

• Working in someone else’s workspace uses an agent seat there, not in yours. If that workspace’s plan is full, the call fails with a message naming the keys taking the seats and who owns them.
• Agent memory stays in the default workspace when no issue is in progress; if you have one claimed, it is stored in that issue’s workspace. See Agent memory.

OAuth works the same way: the workspace you pick when authorizing is the default, not the boundary. And signing a connected app out in Settings revokes its access to all your workspaces at once, not just one.

A key scoped to a project is the exception: it inherits nothing and stays in its project.

The MCP tools

The server exposes a set of tools grouped by function:

• Workspaces: list_workspaces.
• Read: list_issues, get_issue, search_issues, list_projects, list_comments.
• Discovery (to resolve identifiers): list_workflow_states, list_members, list_labels, list_milestones, list_cycles.
• Docs: list_docs, get_doc, save_doc.
• Write: save_issue, change_issue_state, save_project, add_comment, link_issues, unlink_issues.
• Agent orchestration: claim_issue, release_issue, next_ready_issue, record_run.
• Memory: mem_search, mem_context, mem_get, mem_save, mem_session_summary.

With a read-only key, the write, orchestration and memory-save tools don’t appear.

Related: Prompts · Agents · Agent memory · Working framework.