API y MCP

Hilbana expone la misma base de datos por dos vías: una API REST del producto y un servidor MCP (Model Context Protocol) para que un cliente de IA opere el gestor con herramientas.

Claves de API

Se gestionan en Ajustes → Claves de API (solo administradores). Cada clave:

• Tiene el formato hil_… y se muestra completa una sola vez al crearla (después solo se ve su prefijo).
• Tiene un ámbito: todo el workspace o un proyecto concreto. Sin proyecto, la clave alcanza además el resto de workspaces de los que su dueño sea miembro (ver más abajo); acotada a un proyecto, no.
• Puede ser de solo lectura.
• Se puede revocar en cualquier momento.

El endpoint MCP

El servidor MCP vive en https://app.hilbana.com/mcp. Para conectar un cliente como Claude Code:

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

Configuración por fichero

Si tu cliente se configura con un JSON (.mcp.json en la raíz del proyecto, claude_desktop_config.json, el mcp.json de tu editor…), esta es la entrada equivalente. Cópiala y sustituye la clave por la tuya:

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

Si el cliente admite OAuth, quita el bloque headers: te pedirá el login por navegador la primera vez y no tendrás claves que guardar en un fichero.

Autenticación

Dos formas, que conviven:

• Clave de API: pega el Bearer hil_…. El ámbito y el modo solo lectura salen de la propia clave. Es lo recomendado para agentes y servicios (y para entornos headless / CI).
• OAuth 2.1 con registro dinámico de cliente (DCR): login por navegador, sin gestionar claves a mano, para los clientes MCP que lo soporten. Los permisos de escritura dependen del scope concedido.

Varios workspaces con una sola conexión

Una clave identifica a la persona que la creó, no a un workspace. La conexión alcanza todos los workspaces de los que esa persona es miembro, y el workspace donde se creó la clave es simplemente el de por defecto: el que se usa cuando la llamada no dice otra cosa.

En la práctica: si te invitan a otro workspace, no tienes que hacer nada. Tu cliente MCP ya configurado lo alcanza — sin pedirle una clave a su administrador y sin registrar un segundo servidor.

Cómo se dirige el agente:

• list_workspaces enumera los que están a su alcance y marca cuál es el de por defecto.
• Las herramientas que reciben el identificador de una entidad (get_issue, add_comment, change_issue_state…) deducen el workspace de esa entidad: no hay que indicarles nada.
• Las de listado (list_issues, list_projects, search_issues…) aceptan un workspaceId opcional. Sin él usan el de por defecto, así que las sesiones y configuraciones existentes se comportan exactamente igual que antes.
• Las de creación responden diciendo en qué workspace ha quedado lo creado.
• Un identificador como ABC-123 deja de ser único entre workspaces: una búsqueda por identificador puede devolver varias coincidencias, cada una con su workspace.

Dos cosas que conviene saber de antemano:

• Operar en un workspace ajeno consume un asiento de agente allí, no en el tuyo. Si el plan de ese workspace está lleno, la llamada falla con un mensaje que dice qué claves lo están ocupando y de quién son.
• La memoria del agente vive siempre en el workspace por defecto cuando no hay ninguna issue en curso; si hay una reclamada, se guarda en el workspace de esa issue. Ver Memoria de agentes.

Con OAuth es igual: el workspace que eliges al autorizar es el de por defecto, no el límite del acceso. Y cerrar la aplicación conectada en Ajustes le retira el acceso a todos tus workspaces a la vez, no solo a uno.

Una clave acotada a un proyecto es la excepción: no hereda nada y se queda en su proyecto.

Las herramientas MCP

El servidor expone un conjunto de herramientas agrupadas por función:

• Workspaces: list_workspaces.
• Lectura: list_issues, get_issue, search_issues, list_projects, list_comments.
• Descubrimiento (para resolver identificadores): list_workflow_states, list_members, list_labels, list_milestones, list_cycles.
• Documentos: list_docs, get_doc, save_doc.
• Escritura: save_issue, change_issue_state, save_project, add_comment, link_issues, unlink_issues.
• Orquestación de agentes: claim_issue, release_issue, next_ready_issue, record_run.
• Memoria: mem_search, mem_context, mem_get, mem_save, mem_session_summary.

Con una clave de solo lectura, las herramientas de escritura, orquestación y guardado de memoria no aparecen.

Relacionado: Prompts · Agentes · Memoria de agentes · Framework de trabajo.