Montar un agente con MCP y herramientas locales

TL;DR

• Crea un servidor MCP con 2 herramientas (search, shell).
• Conéctalo a OpenClaw.
• Configura el agente para decidir cuándo usar herramientas.
• Ejecuta localmente sin llamar a APIs externas.
• Resultado: un agente que busca información y ejecuta comandos bajo tu control.

Tiempo estimado: 1–2 horas.

---

Prerrequisitos

• Node.js 20+
• npm o yarn
• OpenClaw instalado (npm i -g openclaw)
• Git
• Conocimientos básicos de TypeScript y CLI

---

Paso 1: Proyecto y dependencias

Crea directorio e inicializa:

mkdir mcp-agent-demo && cd mcp-agent-demo
npm init -y
npm install @modelcontextprotocol/sdk openclaw
npm install -D typescript ts-node @types/node
npx tsc --init

tsconfig.json mínimo:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "strict": true,
    "outDir": "dist"
  }
}

---

Paso 2: Servidor MCP con herramientas

Crea src/server.ts:

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
  Tool,
  TextContent,
} from '@modelcontextprotocol/sdk/types.js';

const server = new Server(
  { name: 'demo-agent-tools', version: '1.0.0' },
  { capabilities: { tools: {} } }
);

const tools: Tool[] = [
  {
    name: 'search',
    description: 'Search the web (simulated). Pass query as string.',
    inputSchema: {
      type: 'object',
      properties: {
        query: { type: 'string', description: 'Search query' }
      },
      required: ['query']
    }
  },
  {
    name: 'shell',
    description: 'Execute a shell command (limited allowlist).',
    inputSchema: {
      type: 'object',
      properties: {
        command: { type: 'string', description: 'Command to run' }
      },
      required: ['command']
    }
  }
];

server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
  if (name === 'search') {
    // Simulación; en producción usarías Google Custom Search o similar
    return [{ type: 'text', text: `Simulated results for: ${args.query}` }];
  }
  if (name === 'shell') {
    // Ejecución muy restringida solo para demo
    return [{ type: 'text', text: `Would run: ${args.command}` }];
  }
  throw new Error('Unknown tool');
});

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error('MCP server running on stdio');
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

Ejecuta el servidor:

npx ts-node src/server.ts

Estará listo para conectar por stdio.

---

Paso 3: Configurar OpenClaw

Crea openclaw.config.yaml en la raíz:

agent:
  name: DemoAgent
  description: Agente demo con MCP + herramientas locales
  model: zai/glm-4.5-air # gratuito, rápido
  maxIterations: 10
  tools:
    - mcp: ./src/server.ts
  memory:
    enabled: true
  debug: true

---

Paso 4: Ejecutar el agente

openclaw run

Verás el prompt interactivo. Prueba:

User: busca "precios DeepSeek V4" y luego lista los archivos del directorio actual.

El agente:

1. recognizes que necesita search,
2. calls el tool MCP search,
3. recibe resultados simulados,
4. después llama a shell con ls,
5. devuelve respuesta consolidada.

---

Paso 5: Q&A y problemas comunes

¿Por qué MCP? Para separar herramientas (search, shell, filesystem) del LLM, con un protocolo estándar.

¿OpenClaw? Orquestador ligero que gestiona el bucle agente-herramientas sin que tengas que escribir tu propio controlador.

¿Seguridad? Esta demo es insegura: shell ejecuta cualquier cosa. En producción, usa allowlist estricta, sandbox o evita shell por completo.

¿Costes? Usamos zai/glm-4.5-air que es gratuito. Si cambias a un modelo más caro, controla maxIterations y tokens.

¿Sin Internet? El tool search simula resultados. Cambia la implementación para usar fuentes locales o caché.

---

Paso 6: Limpieza y mejora

Agrega logging, manejo de errores, timeouts, y un frontend si lo necesitas. Este ejemplo es mínimo pero funcional.

---

Siguientes pasos

• Reemplaza search por una API real con límites diarios.
• Añade herramienta file-read, file-write, http-request.
• Implementa memoria persistente con sqlite o redis.
• Escribe pruebas unitarias para el servidor MCP.
• Implementa validación de arguments más estricta.

---

Conclusión

Este tutorial te ha mostrado cómo:

• Crear un servidor MCP en TypeScript,
• exponer herramientas,
• conectar OpenClaw,
• ejecutar un agente localmente sin APIs externas caras.

El resultado es un agente programable, reutilizable, y con coste cero si usas modelos gratuitos.