Naftiko Capabilities for Gravitee

Gravitee splits the API platform into two control planes: the Gravitee Management API for APIs, plans, subscriptions, applications, and platform configuration, and Gravitee Access Management for OAuth2 / OIDC security domains, applications, users, roles, identity providers, and authentication flows. The Naftiko capabilities for Gravitee wrap both control planes — turning the day-to-day work of running the platform into structured tool calls an AI agent can audit, propose, and execute against.

What the Capabilities Cover

Two capabilities ship alongside each other in this repo:

• api-management — the producer / platform-engineer surface. Manage API definitions through their full lifecycle (create → deploy → start / stop → delete), inspect plans and subscriptions, work with applications and users, read platform configuration, and pull audit events.
• access-management — the security-engineer surface. Manage Gravitee AM security domains, OAuth2 / OIDC applications, users, roles, identity providers, and the authentication flows that bind them together.

Together they give an agent a coherent view of what is exposed and who can reach it — the two halves of any real API governance posture.

MCP Tools Available

API Management: list-apis, get-api, create-api, update-api, delete-api, deploy-api, start-api, stop-api, list-api-plans, create-plan, list-api-subscriptions, list-applications, create-application, list-users, get-configuration, list-audit-events

Access Management: list-domains, get-domain, create-domain, update-domain, delete-domain, list-domain-applications, create-domain-application, list-domain-users, create-domain-user, list-domain-roles, list-identity-providers, list-domain-flows

Capability Specification

naftiko: "1.0.0-alpha1"

info:
  label: "Gravitee API Management"
  description: "API management workflow for platform engineers and API producers to manage Gravitee APIs, plans, subscriptions, applications, and platform configuration through the Management API."
  tags:
    - Gravitee
    - API Management
    - Administration

binds:
  - namespace: env
    keys:
      GRAVITEE_MANAGEMENT_URL: GRAVITEE_MANAGEMENT_URL
      GRAVITEE_MANAGEMENT_TOKEN: GRAVITEE_MANAGEMENT_TOKEN

capability:
  consumes:
    - import: gravitee-management
      location: ./shared/gravitee-management.yaml

  exposes:
    - type: mcp
      port: 9080
      namespace: gravitee-api-management-mcp
      transport: http
      description: "MCP server for AI-assisted Gravitee API management."
      tools:
        - name: list-apis
          description: "List all APIs registered in Gravitee."
          hints:
            readOnly: true
          call: "gravitee-management.list-apis"
          outputParameters:
            - type: object
              mapping: "$."

        - name: deploy-api
          description: "Deploy an API definition to the gateway."
          hints:
            readOnly: false
            destructive: false
            idempotent: false
          call: "gravitee-management.deploy-api"
          with:
            apiId: "tools.apiId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: start-api
          description: "Start an API on the gateway."
          hints:
            readOnly: false
          call: "gravitee-management.start-api"
          with:
            apiId: "tools.apiId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-api-plans
          description: "List plans associated with an API."
          hints:
            readOnly: true
          call: "gravitee-management.list-api-plans"
          with:
            apiId: "tools.apiId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-api-subscriptions
          description: "List subscriptions to an API."
          hints:
            readOnly: true
          call: "gravitee-management.list-api-subscriptions"
          with:
            apiId: "tools.apiId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-audit-events
          description: "List recent audit events on the platform."
          hints:
            readOnly: true
          call: "gravitee-management.list-audit-events"
          outputParameters:
            - type: object
              mapping: "$."

The Access Management capability mirrors this shape over gravitee-access-management — domains, applications, users, roles, identity providers, and flows — so the same agent runtime can read and reason about both planes side by side.

Running It

Set GRAVITEE_MANAGEMENT_URL and GRAVITEE_MANAGEMENT_TOKEN (or GRAVITEE_AM_URL / GRAVITEE_AM_TOKEN for the access-management capability) in your .env file, then:

docker pull ghcr.io/naftiko/framework:latest

docker run -p 9080:9080 \
  -v ./capabilities/api-management.yaml:/app/capability.yaml \
  -v ./capabilities/shared:/app/shared \
  --env-file .env \
  ghcr.io/naftiko/framework:latest /app/capability.yaml

Gravitee’s two-plane architecture is exactly the kind of surface where capability-driven exposure earns its keep: an agent that needs to “audit which APIs an external partner can reach” has to read APIs from the management plane, plans and subscriptions from the same plane, and identity-provider and role bindings from the access-management plane — and have all four answers reconciled in a single, governed call graph. With both Gravitee capabilities exposed as MCP, that workflow is a deterministic chain of typed tool calls an operator can replay, audit, and trust. The Gravitee capabilities are part of the Naftiko Fleet.