Agentes AI en PHP con MCP y Neuron

Resumen: Este artículo explica cómo integrar agentes AI escritos en PHP con servidores MCP usando el framework Neuron. Incluye requisitos, flujo de trabajo y ejemplos de código.

Se cubre la arquitectura mínima (Host, MCP server, MCP client), cómo cargar herramientas desde un servidor MCP y ejemplos prácticos en PHP.

• Introducción
• Prerrequisitos
• Desarrollo
• Ejemplos
• Checklist
• Conclusión

Introducción

MCP (Model Context Protocol) normaliza la exposición de APIs y herramientas para que los LLM puedan descubrir y ejecutar funciones. En lugar de implementar cada integración desde cero, un servidor MCP actúa como capa intermedia que traduce y presenta herramientas listas para LLM.

Los modelos de lenguaje por sí solos gestionan texto; necesitan herramientas para ejecutar acciones en el mundo real.

Prerrequisitos

Antes de empezar necesita PHP (versión compatible con su proyecto), Composer y acceso al repositorio de Neuron. También, durante desarrollo, deberá instalar el MCP server localmente.

composer require inspector-apm/neuron-aiLenguaje del código: Bash (bash)

Desarrollo

En términos prácticos MCP requiere tres componentes: un Host donde corre el agente, un MCP server que expone herramientas y un MCP client que permite al agente comunicarse con el servidor (normalmente vía stdio en implementaciones locales).

Procedimiento

• Instalar el MCP server en la misma máquina del agente (desarrollo y producción cuando aplique).
• Configurar el servidor MCP y exponer las herramientas necesarias.
• Usar Neuron y su McpConnector para descubrir y cargar herramientas en el agente.

Neuron integra la conexión con MCP para que, cuando el agente decida ejecutar una herramienta, la petición se envíe al MCP server y el resultado vuelva al LLM como si fuera una herramienta nativa.

Ejemplos

Ejemplo mínimo: un agente PHP que define un proveedor de IA y sus instrucciones. Este ejemplo usa la estructura de Neuron para declarar el proveedor.

<?php
use NeuronAI\Agent;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Anthropic\Anthropic;

class MyAgent extends Agent
{
    public function provider(): AIProviderInterface
    {
        return new Anthropic(
            key: 'ANTHROPIC_API_KEY',
            model: 'ANTHROPIC_MODEL',
        );
    }

    public function instructions(): string
    {
        return "LLM system instructions.";
    }
}
Lenguaje del código: PHP (php)

Agregar herramientas y conectar un MCP server con McpConnector para cargar las herramientas expuestas automáticamente. En este ejemplo se combinan las herramientas recuperadas desde un servidor MCP con herramientas personalizadas.

<?php
use NeuronAI\Agent;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Anthropic\Anthropic;
use NeuronAI\Tools\Tool;
use NeuronAI\Tools\ToolProperty;

class MyAgent extends Agent
{
    public function provider(): AIProviderInterface
    {
        return new Anthropic(
            key: 'ANTHROPIC_API_KEY',
            model: 'ANTHROPIC_MODEL',
        );
    }

    public function instructions(): string
    {
        return "LLM system instructions.";
    }

    public function tools(): array
    {
        return [
           // Cargar herramientas desde un MCP server
           ...McpConnector::make([
                'command' => 'npx',
                'args' => ['-y', '@modelcontextprotocol/server-everything'],
            ])->tools(),
  
            // Herramienta personalizada
            Tool::make(
                "get_article_content", 
                "Use the ID of the article to get its content."
            )->addProperty(
                new ToolProperty(
                    name: 'article_id',
                    type: 'integer',
                    description: 'The ID  of the article you want to analyze.',
                    required: true
                )
            )->setCallable(function (string $article_id) {
                // Use su capa de datos aquí
                global $pdo;
                $stmt = $pdo->prepare("SELECT * FROM articles WHERE id=? LIMIT 1");
                $stmt->execute([$article_id]);
                return json_encode(
                    $stmt->fetch(PDO::FETCH_ASSOC)
                );
            })
        ];
    }
}
Lenguaje del código: PHP (php)

Puede encontrar más ejemplos y una sección de instalación en la documentación oficial: https://docs.neuron-ai.dev/installation

Checklist

1. Instalar Neuron via Composer en el proyecto.
2. Instalar y configurar el MCP server localmente (desarrollo).
3. Usar McpConnector para descubrir y cargar herramientas automáticamente.
4. Definir herramientas personalizadas que usen las APIs internas (DB, servicios externos).
5. Probar el flujo: agente decide, ejecuta herramienta en MCP, recibe resultado y continúa la resolución.

Conclusión

MCP facilita exponer herramientas listas para LLM y reduce la complejidad de integrar múltiples servicios. Con Neuron en PHP puede aprovechar MCP para crear agentes capaces de ejecutar acciones complejas sin replicar integraciones desde cero.

Empiece instalando Neuron, ponga en marcha un MCP server local y use McpConnector para acelerar la integración de herramientas en sus agentes.