headlo-mcp

{
  "mcpServers": {
    "headlo": {
      "command": "npx",
      "args": ["headlo-mcp"],
      "env": {
        "HEADLO_API_TOKEN": "hl_pat_your_token_here"
      }
    }
  }
}

claude mcp add headlo -e HEADLO_API_TOKEN=hl_pat_your_token_here -- npx headlo-mcp

claude mcp add headlo https://api.headlo.com/v1/mcp --header "Authorization: Bearer hl_pat_your_token_here"

npm install headlo-mcp @modelcontextprotocol/sdk

import { createHeadloServer } from 'headlo-mcp'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
import { z } from 'zod'

const server = createHeadloServer()

// your own tool alongside the built-ins
server.tool('my_crm_lookup', 'Look up a contact in my CRM', { email: z.string() }, async ({ email }) => {
  const contact = await myCRM.find(email)
  return { content: [{ type: 'text', text: JSON.stringify(contact) }] }
})

await server.connect(new StdioServerTransport())

import { createHeadloServer } from 'headlo-mcp'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'

const server = createHeadloServer({
  wrap: {
    // validate before creating a record, sync to CRM after
    create_record: async (args, next) => {
      await mySchema.validate(args)
      const result = await next(args)
      await myCRM.push(result)
      return result
    },

    // log every CAP session to your analytics
    cap_capture_expert: async (args, next) => {
      const result = await next(args)
      await myAnalytics.track(args.cap_id, result)
      return result
    },
  }
})

await server.connect(new StdioServerTransport())

// Turn 1 — load the CAP (empty message)
const t1 = await cap_capture_expert({ cap_id: 'abc123def456', message: '' })
// → { response: "Question 1 of 3: ...", session_state: {...}, complete: false }

// Turn 2 — answer the first question, pass session_state back
const t2 = await cap_capture_expert({ cap_id: 'abc123def456', message: 'Downtown', session_state: t1.session_state })
// → { response: "Question 2 of 3: ...", session_state: {...}, complete: false }

// Turn 3 — final answer
const t3 = await cap_capture_expert({ cap_id: 'abc123def456', message: 'Coffee shops', session_state: t2.session_state })
// → { response: "...", complete: true, answer: "..." }

const server = createHeadloServer({
  wrap: {
    cap_capture_expert: async (args, next) => {
      const result = await next(args)
      // log every completed session to your analytics
      if (result.complete) await myAnalytics.track(args.cap_id, result)
      return result
    },
  }
})