naftiko: 1.0.0-alpha2
info:
  label: HashiCorp Vault Secrets Management
  description: Unified workflow capability for platform engineers and DevOps teams managing secrets with HashiCorp Vault.
    Combines KV secrets CRUD, version management, metadata operations, and system configuration into a single AI-accessible
    interface for secrets lifecycle management.
  tags:
  - HashiCorp Vault
  - Secrets Management
  - DevOps
  - Platform Engineering
  - Security
  created: '2026-05-03'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    VAULT_TOKEN: VAULT_TOKEN
    VAULT_ADDR: VAULT_ADDR
capability:
  consumes:
  - type: http
    namespace: vault-kv
    baseUri: '{{VAULT_ADDR}}/v1'
    description: HashiCorp Vault KV v2 secrets engine REST API.
    authentication:
      type: apikey
      key: X-Vault-Token
      value: '{{VAULT_TOKEN}}'
      placement: header
    resources:
    - name: kv-config
      path: /secret/config
      description: KV v2 engine configuration.
      operations:
      - name: get-kv-config
        method: GET
        description: Retrieve KV engine configuration including max versions and CAS settings.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: set-kv-config
        method: POST
        description: Configure KV engine settings such as max versions and CAS required.
        inputParameters:
        - name: max_versions
          in: body
          type: integer
          required: false
          description: Maximum number of versions to keep per secret.
        - name: cas_required
          in: body
          type: boolean
          required: false
          description: Require CAS for all write operations.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            max_versions: '{{tools.max_versions}}'
            cas_required: '{{tools.cas_required}}'
    - name: kv-data
      path: /secret/data/{path}
      description: Secret data CRUD operations with versioning.
      operations:
      - name: read-secret
        method: GET
        description: Read secret data and metadata for a given path. Returns latest version by default.
        inputParameters:
        - name: path
          in: path
          type: string
          required: true
          description: Path to the secret.
        - name: version
          in: query
          type: integer
          required: false
          description: Specific version to retrieve.
        outputRawFormat: json
        outputParameters:
        - name: data
          type: object
          value: $.data.data
        - name: metadata
          type: object
          value: $.data.metadata
      - name: write-secret
        method: POST
        description: Create or update a secret. Each write creates a new version.
        inputParameters:
        - name: path
          in: path
          type: string
          required: true
          description: Path to the secret.
        - name: data
          in: body
          type: object
          required: true
          description: Key-value pairs to store.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            data: '{{tools.data}}'
      - name: delete-latest-secret-version
        method: DELETE
        description: Soft delete the latest version of a secret.
        inputParameters:
        - name: path
          in: path
          type: string
          required: true
          description: Path to the secret.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: kv-metadata
      path: /secret/metadata/{path}
      description: Secret metadata and version history management.
      operations:
      - name: read-secret-metadata
        method: GET
        description: Read metadata and version history for a secret.
        inputParameters:
        - name: path
          in: path
          type: string
          required: true
          description: Path to the secret.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: delete-secret-metadata
        method: DELETE
        description: Permanently delete all metadata and versions for a secret.
        inputParameters:
        - name: path
          in: path
          type: string
          required: true
          description: Path to the secret.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  - type: http
    namespace: vault-sys
    baseUri: '{{VAULT_ADDR}}/v1'
    description: HashiCorp Vault system backend REST API.
    authentication:
      type: apikey
      key: X-Vault-Token
      value: '{{VAULT_TOKEN}}'
      placement: header
    resources:
    - name: health
      path: /sys/health
      description: Vault health and status monitoring.
      operations:
      - name: get-health
        method: GET
        description: Check Vault health status including initialized, sealed, and standby state.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: auth-methods
      path: /sys/auth
      description: Authentication method management.
      operations:
      - name: list-auth-methods
        method: GET
        description: List all currently enabled authentication methods.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: enable-auth-method
        method: POST
        description: Enable a new authentication method at the specified path.
        inputParameters:
        - name: path
          in: path
          type: string
          required: true
          description: Mount path for the auth method.
        - name: type
          in: body
          type: string
          required: true
          description: Auth method type (approle, kubernetes, ldap, etc.).
        - name: description
          in: body
          type: string
          required: false
          description: Human-friendly description.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            type: '{{tools.type}}'
            description: '{{tools.description}}'
      - name: disable-auth-method
        method: DELETE
        description: Disable an authentication method and revoke all associated tokens.
        inputParameters:
        - name: path
          in: path
          type: string
          required: true
          description: Mount path of the auth method to disable.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: secrets-mounts
      path: /sys/mounts
      description: Secrets engine mount management.
      operations:
      - name: list-secrets-mounts
        method: GET
        description: List all mounted secrets engines.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: enable-secrets-engine
        method: POST
        description: Mount a new secrets engine at the specified path.
        inputParameters:
        - name: path
          in: path
          type: string
          required: true
          description: Mount path for the secrets engine.
        - name: type
          in: body
          type: string
          required: true
          description: Secrets engine type (kv, aws, database, pki, transit, etc.).
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            type: '{{tools.type}}'
            description: '{{tools.description}}'
      - name: disable-secrets-engine
        method: DELETE
        description: Unmount a secrets engine and revoke all associated secrets.
        inputParameters:
        - name: path
          in: path
          type: string
          required: true
          description: Mount path of the secrets engine to disable.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: policies
      path: /sys/policies/acl
      description: ACL policy management.
      operations:
      - name: list-policies
        method: GET
        description: List all ACL policies.
        outputRawFormat: json
        outputParameters:
        - name: policies
          type: array
          value: $.data.policies
      - name: read-policy
        method: GET
        description: Read an ACL policy by name.
        inputParameters:
        - name: name
          in: path
          type: string
          required: true
          description: Policy name.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: write-policy
        method: POST
        description: Create or update an ACL policy.
        inputParameters:
        - name: name
          in: path
          type: string
          required: true
          description: Policy name.
        - name: policy
          in: body
          type: string
          required: true
          description: HCL policy document.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            policy: '{{tools.policy}}'
      - name: delete-policy
        method: DELETE
        description: Delete an ACL policy.
        inputParameters:
        - name: name
          in: path
          type: string
          required: true
          description: Policy name.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: leases
      path: /sys/leases
      description: Lease lifecycle management.
      operations:
      - name: lookup-lease
        method: PUT
        description: Look up a lease by ID to get TTL and expiration information.
        inputParameters:
        - name: lease_id
          in: body
          type: string
          required: true
          description: Lease identifier.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            lease_id: '{{tools.lease_id}}'
      - name: renew-lease
        method: PUT
        description: Renew a lease to extend its TTL.
        inputParameters:
        - name: lease_id
          in: body
          type: string
          required: true
          description: Lease identifier.
        - name: increment
          in: body
          type: integer
          required: false
          description: Requested renewal duration in seconds.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            lease_id: '{{tools.lease_id}}'
            increment: '{{tools.increment}}'
      - name: revoke-lease
        method: PUT
        description: Revoke a lease and the associated dynamic secret.
        inputParameters:
        - name: lease_id
          in: body
          type: string
          required: true
          description: Lease identifier.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            lease_id: '{{tools.lease_id}}'
  exposes:
  - type: rest
    port: 8080
    namespace: vault-secrets-api
    description: Unified REST API for HashiCorp Vault secrets lifecycle management.
    resources:
    - path: /v1/secrets/{path}
      name: secrets
      description: KV v2 secret CRUD with versioning.
      operations:
      - method: GET
        name: read-secret
        description: Read a secret from Vault KV v2 by path.
        call: vault-kv.read-secret
        with:
          path: rest.path
          version: rest.version
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: write-secret
        description: Write a secret to Vault KV v2.
        call: vault-kv.write-secret
        with:
          path: rest.path
          data: rest.data
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: delete-secret
        description: Soft delete the latest version of a secret.
        call: vault-kv.delete-latest-secret-version
        with:
          path: rest.path
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/secrets/{path}/metadata
      name: secret-metadata
      description: Secret metadata and version history.
      operations:
      - method: GET
        name: read-secret-metadata
        description: Read metadata and version history for a secret.
        call: vault-kv.read-secret-metadata
        with:
          path: rest.path
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/auth-methods
      name: auth-methods
      description: Vault authentication method management.
      operations:
      - method: GET
        name: list-auth-methods
        description: List all enabled authentication methods.
        call: vault-sys.list-auth-methods
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/mounts
      name: secrets-mounts
      description: Vault secrets engine mount management.
      operations:
      - method: GET
        name: list-secrets-mounts
        description: List all mounted secrets engines.
        call: vault-sys.list-secrets-mounts
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/policies
      name: policies
      description: Vault ACL policy management.
      operations:
      - method: GET
        name: list-policies
        description: List all ACL policies.
        call: vault-sys.list-policies
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/health
      name: health
      description: Vault health status.
      operations:
      - method: GET
        name: get-health
        description: Check Vault health status.
        call: vault-sys.get-health
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: vault-secrets-mcp
    transport: http
    description: MCP server for AI-assisted HashiCorp Vault secrets management workflows.
    tools:
    - name: read-secret
      description: Read a secret from HashiCorp Vault KV v2 store by path. Returns the secret data and version metadata.
      hints:
        readOnly: true
        openWorld: false
      call: vault-kv.read-secret
      with:
        path: tools.path
        version: tools.version
      outputParameters:
      - type: object
        mapping: $.
    - name: write-secret
      description: Write a secret to HashiCorp Vault KV v2. Each write creates a new version.
      hints:
        readOnly: false
        idempotent: false
      call: vault-kv.write-secret
      with:
        path: tools.path
        data: tools.data
      outputParameters:
      - type: object
        mapping: $.
    - name: delete-secret
      description: Soft delete the latest version of a secret in Vault. The data can be recovered with undelete.
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: vault-kv.delete-latest-secret-version
      with:
        path: tools.path
      outputParameters:
      - type: object
        mapping: $.
    - name: read-secret-metadata
      description: Read metadata and version history for a Vault secret including creation time, current version, and all
        version states.
      hints:
        readOnly: true
        openWorld: false
      call: vault-kv.read-secret-metadata
      with:
        path: tools.path
      outputParameters:
      - type: object
        mapping: $.
    - name: list-auth-methods
      description: List all authentication methods enabled in Vault including type, path, and configuration.
      hints:
        readOnly: true
        openWorld: false
      call: vault-sys.list-auth-methods
      outputParameters:
      - type: object
        mapping: $.
    - name: list-secrets-mounts
      description: List all secrets engines mounted in Vault with their type, path, and configuration.
      hints:
        readOnly: true
        openWorld: false
      call: vault-sys.list-secrets-mounts
      outputParameters:
      - type: object
        mapping: $.
    - name: list-policies
      description: List all ACL policies configured in Vault.
      hints:
        readOnly: true
        openWorld: false
      call: vault-sys.list-policies
      outputParameters:
      - type: object
        mapping: $.
    - name: read-policy
      description: Read a specific Vault ACL policy by name to view its path-based access rules.
      hints:
        readOnly: true
        openWorld: false
      call: vault-sys.read-policy
      with:
        name: tools.name
      outputParameters:
      - type: object
        mapping: $.
    - name: write-policy
      description: Create or update a Vault ACL policy with HCL rules defining path-based capabilities.
      hints:
        readOnly: false
        idempotent: true
      call: vault-sys.write-policy
      with:
        name: tools.name
        policy: tools.policy
      outputParameters:
      - type: object
        mapping: $.
    - name: lookup-lease
      description: Look up a Vault lease by ID to check TTL, expiration time, and renewable status.
      hints:
        readOnly: true
        openWorld: false
      call: vault-sys.lookup-lease
      with:
        lease_id: tools.lease_id
      outputParameters:
      - type: object
        mapping: $.
    - name: renew-lease
      description: Renew a Vault lease to extend the TTL of dynamic secrets and tokens.
      hints:
        readOnly: false
        idempotent: false
      call: vault-sys.renew-lease
      with:
        lease_id: tools.lease_id
        increment: tools.increment
      outputParameters:
      - type: object
        mapping: $.
    - name: get-vault-health
      description: Check HashiCorp Vault health status including initialized, sealed, and standby state.
      hints:
        readOnly: true
        openWorld: true
      call: vault-sys.get-health
      outputParameters:
      - type: object
        mapping: $.