Vessel CRM Integration

naftiko: "1.0.0-alpha1"

info:
  label: "Vessel CRM Integration"
  description: >-
    Unified CRM integration capability composing the Vessel CRM API for
    embedded CRM workflows. Enables product teams to build native CRM
    integrations with Salesforce, HubSpot, Zoho, Pipedrive, Close, Freshsales,
    Microsoft Dynamics, and more through a single REST and MCP interface.
    Handles authentication, rate limits, data normalization, and pagination
    automatically.
  tags:
    - Accounts
    - CRM
    - Contacts
    - Deals
    - Embedded Integrations
    - GTM
    - HubSpot
    - Leads
    - Notes
    - Salesforce
    - Tasks
    - Unified API
    - Vessel
  created: "2026-05-03"
  modified: "2026-05-03"

binds:
  - namespace: env
    keys:
      VESSEL_API_TOKEN: VESSEL_API_TOKEN
      VESSEL_ACCESS_TOKEN: VESSEL_ACCESS_TOKEN

capability:
  consumes:
    - import: vessel-crm
      location: ./shared/vessel-crm.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: crm-integration-api
      description: "Unified REST API for embedded CRM integration across Salesforce, HubSpot, and 8+ CRM systems."
      resources:
        - path: /v1/contacts
          name: contacts
          description: "CRM contacts unified across all connected CRM systems"
          operations:
            - method: GET
              name: get-all-contacts
              description: "Get All Contacts"
              call: "vessel-crm.get-all-contacts"
              with:
                accessToken: "rest.accessToken"
                cursor: "rest.cursor"
              outputParameters:
                - type: object
                  mapping: "$."

            - method: POST
              name: create-contact
              description: "Create a Contact"
              call: "vessel-crm.create-contact"
              with:
                accessToken: "rest.accessToken"
                firstName: "rest.firstName"
                lastName: "rest.lastName"
                email: "rest.email"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/deals
          name: deals
          description: "CRM deals and opportunities"
          operations:
            - method: GET
              name: get-all-deals
              description: "Get All Deals"
              call: "vessel-crm.get-all-deals"
              with:
                accessToken: "rest.accessToken"
                cursor: "rest.cursor"
              outputParameters:
                - type: object
                  mapping: "$."

            - method: POST
              name: create-deal
              description: "Create a Deal"
              call: "vessel-crm.create-deal"
              with:
                accessToken: "rest.accessToken"
                name: "rest.name"
                amount: "rest.amount"
                stage: "rest.stage"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/accounts
          name: accounts
          description: "CRM company accounts"
          operations:
            - method: GET
              name: get-all-accounts
              description: "Get All Accounts"
              call: "vessel-crm.get-all-accounts"
              with:
                accessToken: "rest.accessToken"
                cursor: "rest.cursor"
              outputParameters:
                - type: object
                  mapping: "$."

            - method: POST
              name: create-account
              description: "Create an Account"
              call: "vessel-crm.create-account"
              with:
                accessToken: "rest.accessToken"
                name: "rest.name"
                domain: "rest.domain"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/leads
          name: leads
          description: "CRM leads"
          operations:
            - method: GET
              name: get-all-leads
              description: "Get All Leads"
              call: "vessel-crm.get-all-leads"
              with:
                accessToken: "rest.accessToken"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/notes
          name: notes
          description: "CRM notes and activity log"
          operations:
            - method: GET
              name: get-all-notes
              description: "Get All Notes"
              call: "vessel-crm.get-all-notes"
              with:
                accessToken: "rest.accessToken"
              outputParameters:
                - type: object
                  mapping: "$."

            - method: POST
              name: create-note
              description: "Create a Note"
              call: "vessel-crm.create-note"
              with:
                accessToken: "rest.accessToken"
                content: "rest.content"
                contactId: "rest.contactId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/tasks
          name: tasks
          description: "CRM tasks"
          operations:
            - method: GET
              name: get-all-tasks
              description: "Get All Tasks"
              call: "vessel-crm.get-all-tasks"
              with:
                accessToken: "rest.accessToken"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/users
          name: users
          description: "CRM users"
          operations:
            - method: GET
              name: get-all-users
              description: "Get All Users"
              call: "vessel-crm.get-all-users"
              with:
                accessToken: "rest.accessToken"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9080
      namespace: crm-integration-mcp
      transport: http
      description: "MCP server for AI-assisted CRM operations across Salesforce, HubSpot, and 8+ CRM systems."
      tools:
        - name: get-crm-contacts
          description: >-
            List all contacts from the user's connected CRM. Works with
            Salesforce, HubSpot, Zoho, Pipedrive, Close, Freshsales,
            Microsoft Dynamics, and Affinity. All dates are ISO 8601, all
            IDs are normalized to strings.
          hints:
            readOnly: true
            openWorld: true
          call: "vessel-crm.get-all-contacts"
          with:
            accessToken: "tools.accessToken"
            cursor: "tools.cursor"
          outputParameters:
            - type: object
              mapping: "$."

        - name: create-crm-contact
          description: >-
            Create a new contact in the user's connected CRM with first name,
            last name, email, phone, and company information.
          hints:
            readOnly: false
            openWorld: false
          call: "vessel-crm.create-contact"
          with:
            accessToken: "tools.accessToken"
            firstName: "tools.firstName"
            lastName: "tools.lastName"
            email: "tools.email"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-crm-deals
          description: >-
            List all deals/opportunities from the user's connected CRM.
            Returns deal name, amount, stage, close date, and assigned owner.
          hints:
            readOnly: true
            openWorld: true
          call: "vessel-crm.get-all-deals"
          with:
            accessToken: "tools.accessToken"
            cursor: "tools.cursor"
          outputParameters:
            - type: object
              mapping: "$."

        - name: create-crm-deal
          description: >-
            Create a new deal/opportunity in the user's connected CRM.
          hints:
            readOnly: false
            openWorld: false
          call: "vessel-crm.create-deal"
          with:
            accessToken: "tools.accessToken"
            name: "tools.name"
            amount: "tools.amount"
            stage: "tools.stage"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-crm-accounts
          description: >-
            List all company accounts from the user's connected CRM.
          hints:
            readOnly: true
            openWorld: true
          call: "vessel-crm.get-all-accounts"
          with:
            accessToken: "tools.accessToken"
            cursor: "tools.cursor"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-crm-leads
          description: "List all leads from the user's connected CRM."
          hints:
            readOnly: true
            openWorld: true
          call: "vessel-crm.get-all-leads"
          with:
            accessToken: "tools.accessToken"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-crm-notes
          description: "List all notes from the user's connected CRM."
          hints:
            readOnly: true
            openWorld: true
          call: "vessel-crm.get-all-notes"
          with:
            accessToken: "tools.accessToken"
          outputParameters:
            - type: object
              mapping: "$."

        - name: create-crm-note
          description: "Create a new note in the user's connected CRM."
          hints:
            readOnly: false
            openWorld: false
          call: "vessel-crm.create-note"
          with:
            accessToken: "tools.accessToken"
            content: "tools.content"
            contactId: "tools.contactId"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-crm-tasks
          description: "List all tasks from the user's connected CRM."
          hints:
            readOnly: true
            openWorld: true
          call: "vessel-crm.get-all-tasks"
          with:
            accessToken: "tools.accessToken"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-crm-users
          description: "List all users from the user's connected CRM."
          hints:
            readOnly: true
            openWorld: true
          call: "vessel-crm.get-all-users"
          with:
            accessToken: "tools.accessToken"
          outputParameters:
            - type: object
              mapping: "$."