Servidor MCP de Websets de Exa

Un servidor del Protocolo de Contexto de Modelo (MCP) que integra la API de Websets de Exa con Claude Desktop, Cursor, Windsurf y otros clientes compatibles con MCP.

¿Qué son los Websets?

Los Websets son colecciones de entidades web (empresas, personas, artículos de investigación) que pueden ser descubiertas, verificadas y enriquecidas automáticamente con datos personalizados. Piense en ellos como hojas de cálculo inteligentes que se actualizan automáticamente mediante investigación web con IA.

Capacidades clave:

• 🔍 Búsqueda automatizada: Encuentre entidades que coincidan con criterios en lenguaje natural

• 📊 Enriquecimiento de datos: Extraiga información personalizada utilizando agentes de IA

• 🎯 Verificación: La IA valida que las entidades cumplan con sus criterios

• 🔗 Webhooks: Notificaciones en tiempo real para actualizaciones de colecciones

• 📥 Importaciones: Traiga sus propios datos CSV a Websets para enriquecimiento o alcance

Related MCP server: Exa Websets MCP Server

Herramientas disponibles

Este servidor MCP proporciona las siguientes herramientas:

Gestión de Websets

Gestión de elementos

Operaciones de búsqueda

Operaciones de enriquecimiento

Webhooks

Importaciones

Eventos

Instalación

Instalación a través de Smithery

Para instalar Exa Websets automáticamente a través de Smithery:

npx -y @smithery/cli install @exa-labs/websets-mcp-server

Requisitos previos

• Node.js v18 o superior

• Claude Desktop, Cursor u otro cliente compatible con MCP

• Una clave de API de Exa de exa.ai

Uso de Claude Code (Recomendado)

La forma más rápida de configurar Websets MCP:

claude mcp add websets -e EXA_API_KEY=YOUR_API_KEY -- npx -y websets-mcp-server

Reemplace YOUR_API_KEY con su clave de API de Exa.

Uso de NPX

# Install globally
npm install -g websets-mcp-server

# Or run directly with npx
npx websets-mcp-server

Configuración

Configuración de Claude Desktop

1. Habilitar el modo desarrollador

   • Abra Claude Desktop

   • Haga clic en el menú → Habilitar modo desarrollador

   • Vaya a Configuración → Desarrollador → Editar configuración

2. Añadir al archivo de configuración:

   macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   Windows: %APPDATA%\Claude\claude_desktop_config.json

   {
     "mcpServers": {
       "websets": {
         "command": "npx",
         "args": [
           "-y",
           "websets-mcp-server"
         ],
         "env": {
           "EXA_API_KEY": "your-api-key-here"
         }
       }
     }
   }

3. Reiniciar Claude Desktop

   • Cierre completamente Claude Desktop

   • Inícielo de nuevo

   • Busque el icono 🔌 para verificar la conexión

Configuración de Cursor y Claude Code

Utilice la configuración basada en HTTP. Pase su clave de API de Exa como un token Bearer en el encabezado Authorization (o como un parámetro de consulta ?exaApiKey=... como alternativa):

{
  "mcpServers": {
    "websets": {
      "type": "http",
      "url": "https://websetsmcp.exa.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_EXA_API_KEY"
      }
    }
  }
}

Referencia del esquema de herramientas

⚠️ Importante para llamadores de IA: Consulte TOOL_SCHEMAS.md para conocer los formatos exactos de los parámetros y ejemplos.

Reglas clave del esquema:

• criteria debe ser una matriz de objetos: [{description: "..."}] (NO una matriz de cadenas)

• entity debe ser un objeto: {type: "company"} (NO una cadena)

• options debe ser una matriz de objetos: [{label: "..."}] (NO una matriz de cadenas)

Estos formatos garantizan la coherencia en todas las herramientas y coinciden con la especificación de la API de Websets.

Ejemplos de uso

Una vez configurado, puede pedirle a Claude que interactúe con Websets:

Creación de un Webset

Create a webset of AI startups in San Francisco with 20 companies. 
Add enrichments for revenue, employee count, and funding stage.

Listado y visualización de Websets

List all my websets and show me the details of the one called "AI Startups"

Gestión de elementos

Show me the first 10 items from my "AI Startups" webset with all their enrichment data

Añadir más elementos

Run another search on my "AI Startups" webset for 20 more companies focused on
enterprise voice agents, appending to the existing items

Enriquecimientos avanzados

Add an enrichment to my webset that extracts the company's latest product launch 
and the CEO's LinkedIn profile

Flujo de trabajo de ejemplo

Aquí tiene un flujo de trabajo completo para construir una base de datos de investigación de empresas:

1. Crear la colección:

   Create a webset called "SaaS Companies" that searches for 
   "B2B SaaS companies with $10M+ revenue"

2. Añadir enriquecimientos:

   Add enrichments to extract: annual recurring revenue, number of customers, 
   primary market segment, and tech stack used

3. Suscribirse a eventos:

   Create a webhook to https://example.com/hook subscribed to
   webset.search.completed and webset.enrichment.completed

4. Ver resultados:

   Show me all items with their enrichment data, sorted by revenue

Detalles de la herramienta

create_webset

Crea una nueva colección de webset con población y enriquecimientos automáticos opcionales.

Parámetros:

• externalId (opcional): Su propio identificador para el webset (máx. 300 caracteres)

• searchQuery (opcional): Consulta en lenguaje natural para encontrar entidades

• searchCount (opcional): Número de entidades a encontrar (predeterminado: 10, mín: 1)

• searchEntity (opcional): Tipo de entidad para la búsqueda, p. ej., {type: "company"}. Para el tipo "custom" incluya una description.

• searchCriteria (opcional): Criterios de filtrado adicionales — [{description: "..."}] (máx. 5)

• searchBehavior (opcional): "override" (predeterminado) reemplaza los elementos existentes, "append" los añade

• searchExclude (opcional): Importaciones/websets cuyos resultados excluir — [{source: "webset"|"import", id: "..."}]

• searchScope (opcional): Limitar la búsqueda a una importación o webset existente — permite búsquedas de salto con una relationship

• searchRecall (opcional): Si calcular métricas de recuperación para la búsqueda

• searchMaxPeoplePerCompany (opcional): Límite suave de personas por empleador para búsquedas de personas

• searchMetadata (opcional): Metadatos clave-valor para asociar con la búsqueda

• enrichments (opcional): Enriquecimientos de datos para extraer automáticamente para cada elemento

• metadata (opcional): Metadatos clave-valor para asociar con el webset

• excludes (opcional): Exclusiones globales — fuentes cuyos resultados se omiten en todas las operaciones en este webset

Nota: no hay un parámetro name o description de nivel superior en el propio webset. Use update_webset con title después de la creación, o metadata para adjuntar pares clave-valor arbitrarios.

Ejemplo:

{
  "externalId": "tech-unicorns-2024",
  "searchQuery": "Technology companies valued over $1 billion",
  "searchCount": 50,
  "searchEntity": {"type": "company"},
  "searchCriteria": [
    {"description": "Valued at over $1 billion"},
    {"description": "Technology sector"}
  ],
  "enrichments": [
    {
      "description": "Current company valuation in USD",
      "format": "number"
    },
    {
      "description": "Names of company founders",
      "format": "text"
    },
    {
      "description": "Company stage",
      "format": "options",
      "options": [
        {"label": "Series A"},
        {"label": "Series B"},
        {"label": "Series C+"},
        {"label": "Public"}
      ]
    }
  ]
}

create_enrichment

Añade un nuevo enriquecimiento de datos para extraer información personalizada de cada elemento del webset.

Parámetros:

• websetId: El ID del webset

• description: Descripción detallada de qué extraer

• format (opcional): Uno de "text", "date", "number", "options", "email", "phone", "url" — seleccionado automáticamente si se omite

• options (opcional): Cuando format es "options", las opciones que elige el agente de enriquecimiento — [{label: "..."}]

• metadata (opcional): Metadatos clave-valor para asociar con este enriquecimiento

Ejemplo:

{
  "websetId": "webset_abc123",
  "description": "Total number of full-time employees as of the most recent data",
  "format": "number"
}

Los monitores (actualización/búsqueda programada) están expuestos por la API de Websets subyacente pero actualmente no se muestran como herramientas MCP en este servidor. Configure los monitores directamente a través de la API de Websets o websets.exa.ai.

Puntos finales de la API

El servidor se conecta a la API de Websets de Exa en https://api.exa.ai/websets/v0.

Documentación completa de la API: docs.exa.ai/reference/websets

Configuración avanzada

Habilitar solo herramientas específicas

Para habilitar solo ciertas herramientas, use la configuración enabledTools:

{
  "mcpServers": {
    "websets": {
      "command": "npx",
      "args": [
        "-y",
        "websets-mcp-server",
        "--tools=create_webset,list_websets,list_webset_items"
      ],
      "env": {
        "EXA_API_KEY": "your-api-key-here"
      }
    }
  }
}

Modo de depuración

Habilite el registro de depuración para solucionar problemas:

{
  "mcpServers": {
    "websets": {
      "command": "npx",
      "args": [
        "-y",
        "websets-mcp-server",
        "--debug"
      ],
      "env": {
        "EXA_API_KEY": "your-api-key-here"
      }
    }
  }
}

Solución de problemas

Problemas de conexión

1. Verifique que su clave de API sea válida

2. Asegúrese de que no haya espacios ni comillas alrededor de la clave de API

3. Reinicie completamente su cliente MCP (no solo cierre la ventana)

4. Compruebe los registros de MCP para ver mensajes de error

Límites de tasa de la API

La API de Websets tiene los siguientes límites:

• Compruebe los límites de su plan en exa.ai/dashboard

• Use paginación para websets grandes

• Supervise el uso de la API en su panel de control

Errores comunes

• 401 No autorizado: Clave de API no válida o faltante

• 404 No encontrado: El ID del webset no existe o fue eliminado

• 422 Procesable: Formato de consulta o criterios no válido

• 429 Límite de tasa: Demasiadas solicitudes, espere y vuelva a intentarlo

Recursos

• Documentación de Websets de Exa

• Panel de control de Exa

• Especificación del protocolo MCP

• Obtener una clave de API de Exa

Desarrollo

Construcción desde el código fuente

git clone https://github.com/exa-labs/websets-mcp-server.git
cd websets-mcp-server
npm install
npm run build

Estructura del proyecto

websets-mcp-server/
├── src/
│   ├── index.ts              # Main server setup
│   ├── types.ts              # TypeScript type definitions
│   ├── tools/                # MCP tool implementations
│   │   ├── config.ts         # API configuration
│   │   ├── createWebset.ts
│   │   ├── listWebsets.ts
│   │   ├── getWebset.ts
│   │   ├── updateWebset.ts
│   │   ├── deleteWebset.ts
│   │   ├── listItems.ts
│   │   ├── createEnrichment.ts
│   │   ├── createSearch.ts
│   │   ├── createWebhook.ts
│   │   ├── createImport.ts
│   │   └── ...
│   └── utils/
│       ├── api.ts            # Shared API client and error handling
│       └── logger.ts         # Logging utilities
├── package.json
└── tsconfig.json

Licencia

MIT

Contribución

¡Las contribuciones son bienvenidas! Por favor, abra un problema o PR en github.com/exa-labs/websets-mcp-server.

Soporte

• Documentación: docs.exa.ai

• Discord: Únase a la comunidad de Exa

• Correo electrónico: support@exa.ai