> ## Documentation Index
> Fetch the complete documentation index at: https://docs.horneross.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Horneross MCP Server

> Gestioná tus empleados de IA desde Claude Code, Cursor, Claude Desktop y cualquier cliente MCP.

El **Horneross MCP Server** es un servidor MCP público que te permite gestionar toda tu cuenta de Horneross desde cualquier cliente compatible con el Model Context Protocol: Claude Code, Cursor, Claude Desktop, Windsurf, y más.

```
┌──────────────────┐      ┌──────────────────────────────────┐      ┌─────────────┐
│  Claude Code /   │ MCP  │  Horneross MCP Server            │ API  │  Horneross  │
│  Cursor / etc.   │ ───→ │  horneross-mcp.lucas-220.workers │ ───→ │  Platform   │
└──────────────────┘      └──────────────────────────────────┘      └─────────────┘
```

## Conexión rápida

<Steps>
  <Step title="Obtené tu API Key">
    Andá a [app.horneross.com](https://app.horneross.com) → **Settings** → **API Keys** → Copiá tu clave.
  </Step>

  <Step title="Configurá tu cliente MCP">
    Agregá el servidor en la configuración de tu cliente. Abajo tenés ejemplos para cada uno.
  </Step>

  <Step title="Listo">
    Ya podés gestionar empleados de IA, datastores, conversaciones y más desde tu editor o terminal.
  </Step>
</Steps>

## Configuración por cliente

<Tabs>
  <Tab title="Claude Code">
    Editá `~/.claude/.mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "horneross": {
          "type": "url",
          "url": "https://horneross-mcp.lucas-220.workers.dev/mcp",
          "headers": {
            "Authorization": "Bearer TU_API_KEY"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Desktop">
    Editá `claude_desktop_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "horneross": {
          "url": "https://horneross-mcp.lucas-220.workers.dev/mcp",
          "headers": {
            "Authorization": "Bearer TU_API_KEY"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Cursor">
    Andá a **Settings** → **MCP** → **Add Server**:

    * **Name**: `horneross`
    * **URL**: `https://horneross-mcp.lucas-220.workers.dev/mcp`
    * **Headers**: `Authorization: Bearer TU_API_KEY`
  </Tab>

  <Tab title="OpenCode">
    Editá `~/.config/opencode/opencode.json` y agregá el servidor en la sección `mcp`:

    ```json theme={null}
    {
      "mcp": {
        "horneross": {
          "enabled": true,
          "type": "remote",
          "url": "https://horneross-mcp.lucas-220.workers.dev/mcp",
          "headers": {
            "Authorization": "Bearer TU_API_KEY"
          }
        }
      }
    }
    ```

    Si ya tenés otros MCP (por ejemplo `context7` o `engram`), mantenelos en el mismo objeto `mcp`.
  </Tab>
</Tabs>

## Herramientas disponibles (102)

El servidor expone 102 herramientas organizadas en 17 módulos. Abajo están las categorías principales para configurar y operar empleados de IA.

### Empleados de IA (8)

| Herramienta           | Descripción                                               |
| --------------------- | --------------------------------------------------------- |
| `list_agents`         | Listar todos los empleados de IA de la organización       |
| `get_agent`           | Obtener detalle de un empleado (config, tools, versiones) |
| `get_agent_config`    | Obtener configuración runtime (modelo, tools, settings)   |
| `create_agent`        | Crear un nuevo empleado de IA                             |
| `update_agent`        | Actualizar solo metadata: nombre y descripción            |
| `update_agent_config` | Cambiar modelo, temperatura, toggles de herramientas      |
| `delete_agent`        | Eliminar un empleado permanentemente                      |
| `chat_with_agent`     | Enviar un mensaje y obtener respuesta                     |

<Accordion title="Ejemplo: Crear un empleado de IA">
  ```
  Usá la herramienta create_agent con:
  - name: "Soporte Técnico"
  - description: "Atiende consultas técnicas"
  - model_name: "gpt_5_2_instant"
  - temperature: 0.3
  - system_prompt: "Sos un agente de soporte técnico. Respondé de forma clara y concisa."
  ```
</Accordion>

<Accordion title="Toggles de update_agent_config">
  Podés activar o desactivar estas capacidades:

  | Toggle                    | Descripción                       |
  | ------------------------- | --------------------------------- |
  | `use_thinking`            | Razonamiento extendido            |
  | `use_web_search`          | Búsqueda web                      |
  | `use_deep_search`         | Búsqueda profunda                 |
  | `use_code_interpreter`    | Intérprete de código              |
  | `use_send_files`          | Envío de archivos                 |
  | `use_markdown`            | Formato markdown                  |
  | `include_sources`         | Incluir fuentes                   |
  | `restrict_knowledge`      | Restringir a base de conocimiento |
  | `use_language_detection`  | Detección de idioma               |
  | `use_conversational_mode` | Modo conversacional               |
  | `use_content_filter`      | Filtro de contenido               |
  | `use_follow_up`           | Sugerencias de seguimiento        |
</Accordion>

### Prompt del sistema (6)

Estas herramientas son el único camino MCP para modificar instrucciones después de crear un agente. Cada escritura guarda una nueva `AgentPromptVersion`.

| Herramienta                | Descripción                      |
| -------------------------- | -------------------------------- |
| `get_system_prompt`        | Leer el prompt efectivo actual   |
| `set_system_prompt`        | Reemplazar el prompt completo    |
| `append_to_system_prompt`  | Agregar texto al final           |
| `prepend_to_system_prompt` | Agregar texto al inicio          |
| `replace_in_system_prompt` | Buscar y reemplazar texto exacto |
| `clear_system_prompt`      | Vaciar el prompt                 |

### Versiones de prompt (3)

Solo los cambios de instrucciones/prompt generan versiones. Cambios runtime como modelo, temperatura, tools, MCP, capacidades o colaboradores actualizan la configuración actual del agente y no crean historial nuevo.

| Herramienta                       | Descripción                                                 |
| --------------------------------- | ----------------------------------------------------------- |
| `list_agent_prompt_versions`      | Listar las últimas 10 versiones de prompt                   |
| `get_agent_prompt_version_config` | Ver config efectiva de una versión de prompt                |
| `activate_agent_prompt_version`   | Activar una versión anterior de prompt sin revertir runtime |

### Conversaciones (2)

| Herramienta                 | Descripción                                    |
| --------------------------- | ---------------------------------------------- |
| `list_conversations`        | Listar conversaciones recientes de un empleado |
| `get_conversation_messages` | Obtener todos los mensajes de una conversación |

### Datastores (3)

| Herramienta         | Descripción                                     |
| ------------------- | ----------------------------------------------- |
| `list_datastores`   | Listar bases de conocimiento                    |
| `query_datastore`   | Buscar en una base con lenguaje natural         |
| `create_datasource` | Agregar contenido: URL, sitio web, texto o Q\&A |

<Accordion title="Tipos de datasource">
  | Tipo       | Descripción             | Parámetros           |
  | ---------- | ----------------------- | -------------------- |
  | `web_page` | Página web individual   | `source_url`         |
  | `web_site` | Crawl de sitio completo | `source_url`         |
  | `text`     | Texto plano             | `content`            |
  | `qa`       | Par pregunta-respuesta  | `question`, `answer` |
</Accordion>

### Tasks / Triggers (3)

| Herramienta   | Descripción                                   |
| ------------- | --------------------------------------------- |
| `list_tasks`  | Listar tareas (triggers) de la organización   |
| `create_task` | Crear un trigger: cron, keyword, evento, etc. |
| `toggle_task` | Activar o desactivar una tarea                |

<Accordion title="Tipos de task">
  | Tipo                 | Ejemplo                                            |
  | -------------------- | -------------------------------------------------- |
  | `schedule`           | Cron: `0 9 * * 1` (lunes 9am)                      |
  | `keyword`            | Se activa cuando el usuario dice una palabra clave |
  | `phrase`             | Se activa con una frase exacta                     |
  | `conversation_start` | Al iniciar conversación                            |
  | `lead_captured`      | Cuando se captura un lead                          |
  | `form_submitted`     | Cuando se envía un formulario                      |
  | `human_requested`    | Cuando el usuario pide hablar con humano           |
</Accordion>

### Herramientas del empleado (3)

| Herramienta         | Descripción                                              |
| ------------------- | -------------------------------------------------------- |
| `list_agent_tools`  | Ver herramientas configuradas en un empleado             |
| `add_agent_tool`    | Agregar herramienta: datastore, HTTP, lead capture, etc. |
| `remove_agent_tool` | Quitar herramienta por ID                                |

### MCP Custom (3)

| Herramienta         | Descripción                                    |
| ------------------- | ---------------------------------------------- |
| `list_custom_mcps`  | Listar servidores MCP conectados a un empleado |
| `add_custom_mcp`    | Conectar un servidor MCP personalizado         |
| `remove_custom_mcp` | Desconectar un servidor MCP                    |

## Autenticación

Todas las requests requieren un header `Authorization` con tu API Key de Horneross:

```
Authorization: Bearer TU_API_KEY
```

La API Key se obtiene desde [app.horneross.com](https://app.horneross.com) → **Settings** → **API Keys**.

## Protocolo

El servidor implementa MCP sobre HTTP (JSON-RPC 2.0):

* **URL**: `https://horneross-mcp.lucas-220.workers.dev/mcp`
* **Método**: `POST` (JSON-RPC)
* **GET**: Devuelve info del servidor y lista de herramientas

```bash theme={null}
# Verificar que el servidor está activo
curl https://horneross-mcp.lucas-220.workers.dev/mcp
```

```json theme={null}
{
  "name": "horneross",
  "version": "0.1.0",
  "description": "Horneross MCP Server — manage AI agents via Model Context Protocol",
  "toolCount": 102,
  "tools": [
    { "name": "list_agents", "description": "List all AI agents..." },
    ...
  ]
}
```

## Agregar un MCP propio para usar en tus empleados

Para que un servidor MCP externo aparezca en tu cliente (Claude Code, Cursor, etc.), agregalo al archivo `~/.claude/.mcp.json` de esa misma máquina, por ejemplo:

```json theme={null}
{
  "mcpServers": {
    "mi-mcp-personal": {
      "type": "url",
      "url": "https://mcp.ejemplo.com/mcp",
      "headers": {
        "Authorization": "Bearer TU_TOKEN"
      }
    }
  }
}
```

Si usás configuración por proyecto de Claude, también puede existir en `~/.claude/projects/<nombre-proyecto>/settings.json`.

Luego, desde Horneross, conectalo al empleado vía API REST de Custom MCP:

```bash theme={null}
curl -X POST "https://app.horneross.com/api/agents/ag_123/custom-mcp" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mi MCP personal",
    "mcpUrl": "https://mcp.ejemplo.com/mcp",
    "type": "streamable-http",
    "enabledTools": ["check_stock", "crear_orden"]
  }'
```

Ese `type` acepta `http`, `sse` o `streamable-http` según el transporte de tu servidor.

## Verificación rápida

Podés verificar que quedó registrado en el empleado:

```bash theme={null}
curl -X GET "https://app.horneross.com/api/agents/ag_123/custom-mcp" \
  -H "Authorization: Bearer sk_live_xxx"
```

La respuesta trae un array de MCPs con `id`, `name`, `type`, `url` y `enabledTools`.

Para borrar un MCP, reutilizá ese `id`:

```bash theme={null}
curl -X DELETE https://app.horneross.com/api/agents/ag_123/custom-mcp \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"mcpId": "custom_http_xxx"}'
```

## Casos de uso

<CardGroup cols={2}>
  <Card title="Gestión desde IDE" icon="code">
    Creá y configurá empleados de IA sin salir de tu editor de código.
  </Card>

  <Card title="Automatización CI/CD" icon="gears">
    Actualizá prompts y configuraciones como parte de tu pipeline de deploy.
  </Card>

  <Card title="Debugging" icon="bug">
    Inspeccioná conversaciones, versiones y configuraciones desde la terminal.
  </Card>

  <Card title="Versionado" icon="code-branch">
    Revisá el historial de cambios y restaurá versiones anteriores.
  </Card>
</CardGroup>

## Próximos pasos

<CardGroup cols={2}>
  <Card title="MCP Overview" icon="plug" href="/developers/mcp/index">
    Conectar servidores MCP externos a tus empleados
  </Card>

  <Card title="API Reference" icon="code" href="/developers/api/index">
    Documentación completa de la API REST
  </Card>
</CardGroup>