convez.ai
MCP ServerIntegração & APIsIntermediário
headlohq

Headlo MCP Server

headlohq/headlo-mcp

Integração Headlo para Claude com acesso a coleções e registros

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que integra Headlo com Claude Desktop e Claude Code, dando acesso direto a coleções, registros, páginas e componentes. Funciona como servidor standalone ou biblioteca extensível para adicionar ferramentas customizadas e interceptar handlers built-in.

Instalação

$npx convez-ai headlohq/headlo-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
50%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Acessar e gerenciar coleções Headlo via Claude Desktop
  • Criar e atualizar registros em coleções através de prompts
  • Estender o servidor com ferramentas customizadas e validações
  • Sincronizar dados Headlo com sistemas externos (CRM, analytics)

Veredito

MCP server bem estruturado para quem usa Headlo e precisa integrá-lo ao fluxo Claude. Extensível via TypeScript, com bom suporte a interceptação de handlers. Requer token Headlo válido e é ideal para automação de workflows entre Headlo e Claude.

README

A tradução para o português deste README ainda está na fila.

headlo-mcp

MCP server for Headlo — gives Claude Desktop and Claude Code access to your Headlo collections, records, pages, and components.

Use it as a standalone server, or install as a library to add your own tools and intercept built-in ones.

Quickstart

Claude Desktop

Edit claude_desktop_config.json (Mac: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

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

Restart Claude Desktop. You should see the Headlo tools available.

Claude Code

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

Remote MCP (no install)

If you don't need to extend the server, point Claude directly at the Headlo API:

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

Extending the server

Install as a library to add your own tools or intercept built-in ones:

npm install headlo-mcp @modelcontextprotocol/sdk

Add custom tools

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())

Intercept built-in tool calls

Pass a wrap map to run code before or after any built-in tool:

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())

next(args) calls the original Headlo handler. You can modify args before passing them, or modify the result before returning it.


Environment variables

VariableRequiredDescription
HEADLO_API_TOKENYesYour Headlo API token (hl_pat_...)
HEADLO_API_URLNoAPI base URL (default: https://api.headlo.com)
HEADLO_ANON_KEYNoAnon key for public tool calls

Built-in tools

Context

ToolDescription
get_contextList all sites and workspaces — call this first

Collections

ToolDescription
list_collectionsList all collections in a workspace
create_collectionCreate a new collection with a schema
update_collectionUpdate a collection label or schema

Records

ToolDescription
list_recordsList records in a collection (includes drafts)
get_recordGet a single record by ID
create_recordCreate a new record
update_recordUpdate a record (partial — only provided fields change)
delete_recordDelete a record

Pages

ToolDescription
list_pagesList all pages for a site
create_pageCreate a new page
update_pageUpdate a page title, layout, or status

Modules

ToolDescription
list_modules_editorList all modules on a page
create_moduleAdd a module to a page slot
update_moduleUpdate a module's record, options, or template
delete_moduleRemove a module from a page

Public

ToolDescription
list_page_modulesList modules on a page (anon auth)
get_moduleGet a single module (anon auth)

CAP (Context Accumulation Protocol)

CAP is Headlo's expert intake system — structured question flows backed by pre-researched knowledge that produce better AI answers than generic prompts.

ToolDescription
create_expert_protocolCreate a new CAP with intake questions and knowledge probes for a question on the Ask network
cap_capture_expertRun a CAP as a live multi-turn intake session — call with empty message to start, pass answers in subsequent calls
cap_edit_expertConversationally edit an existing CAP — add/remove questions, edit options

Running a CAP session (multi-turn):

// 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: "..." }

Intercepting CAP calls with middleware:

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
    },
  }
})

Onboarding

ToolDescription
setup_agencyCreate a new agency/workspace
create_siteCreate a new site
save_brandingSave logo and brand color
get_onboarding_progressGet current onboarding step

License

Elastic License 2.0 — © Headlo

Source available. Free for internal use. Production self-hosting requires a commercial license.

Built by Headlo.

Ver o original no GitHub

Bom para

Relacionados