Demostración de MCP Agent Harness

Una demostración mínima de un harness de agente LLM que utiliza el Protocolo de Contexto de Modelo (MCP).

Este repositorio contiene pequeños ejemplos en Node.js/TypeScript y Python que muestran cómo un agente puede:

• descubrir herramientas de un servidor MCP;

• exponer esas herramientas a un LLM;

• permitir que el modelo solicite llamadas a herramientas;

• ejecutar esas llamadas a través de MCP;

• devolver los resultados de las herramientas al modelo;

• continuar el bucle hasta que el modelo produzca una respuesta final.

Importante: Este es solo código de demostración. No es código de producción y no debe tratarse como un marco de agente seguro, robusto o completo.

El propósito del repositorio es facilitar la inspección de la mecánica de un harness de agente basado en MCP.

Arquitectura

A alto nivel:

User
  |
  v
LLM
  |
  | tool request
  v
Agent Harness
  |
  v
MCP Client
  |
  v
MCP Server
  |
  v
Tool Implementation
  |
  v
Tool Result
  |
  +------------------> LLM

Las responsabilidades están deliberadamente separadas:

LLM      - decides what it thinks should happen
Harness  - manages the agent loop and conversation state
MCP      - standardises tool discovery and invocation
Tools    - perform the actual deterministic operations

MCP no decide qué herramienta debe llamarse.

La selección de herramientas sigue siendo una decisión del modelo a menos que la aplicación circundante la restrinja o anule explícitamente.

Related MCP server: MCP Server Scaffold

Por Qué Existe Este Repositorio

Gran parte de la terminología de los marcos de agentes puede ocultar lo que realmente está sucediendo.

El bucle esencial del harness es poco más que:

call model
    |
    v
did it request a tool?
    |
   / \
 no   yes
 |     |
answer execute tool
       |
       v
   return result
       |
       +----> call model again

Este repositorio mantiene ese mecanismo visible en lugar de ocultarlo detrás de un gran marco de agente.

Estructura del Repositorio

Una estructura típica es:

.
├── node/
│   ├── package.json
│   └── src/
│       ├── agent.ts
│       └── server.ts
│
└── python/
    ├── agent.py
    └── server.py

Los nombres exactos de los directorios se pueden cambiar sin afectar la arquitectura.

Ejemplo de Herramientas MCP

El servidor de demostración expone tres herramientas hipotéticas deliberadamente simples:

get_github_activity
get_site_content
contact_scott

Estos son solo ejemplos destinados a demostrar:

• descubrimiento de herramientas;

• esquemas de herramientas;

• descripciones de herramientas;

• argumentos;

• ejecución;

• manejo de resultados.

No pretenden representar un backend real.

Node.js / TypeScript

Requisitos

• Node.js 20+

• una clave API de OpenAI

Instala las dependencias:

npm install

Configura la clave API:

export OPENAI_API_KEY="sk-..."

Ejecuta el agente:

npm start

El servidor MCP se inicia automáticamente por el agente a través del transporte stdio.

No deberías necesitar ejecutar el servidor por separado.

Salida de ejemplo:

MCP tools: [
  'get_github_activity',
  'get_site_content',
  'contact_scott'
]

MODEL REQUESTED TOOL: get_github_activity
ARGUMENTS: {}

MCP RESULT:
...

FINAL ANSWER
------------
Scott has recently been working on...

Python

Requisitos

• Python 3.10+

• una clave API de OpenAI

Crea un entorno virtual:

python3 -m venv .venv
source .venv/bin/activate

Actualiza las herramientas de empaquetado:

python3 -m pip install --upgrade pip setuptools wheel

Instala las dependencias:

pip install "mcp>=2,<3" openai

Configura la clave API:

export OPENAI_API_KEY="sk-..."

Ejecuta:

python3 agent.py

La versión en Python se ejecuta como un chatbot CLI interactivo:

MCP tools: ['get_github_activity', 'get_site_content', 'contact_scott']

Chat started.
Type /quit to exit.

You> hello

Assistant> Hello! How can I help?

You> What has Scott been working on?

  [tool] get_github_activity({})
  [result] ...

Assistant> Scott has recently been working on...

El cliente de Python conserva el historial de conversación entre turnos y transmite respuestas normales al terminal.

Transporte Stdio

Estos ejemplos utilizan MCP a través de stdio.

El agente inicia el servidor MCP como un proceso hijo:

agent
  |
  +---- stdin/stdout ---- MCP server

Esto es conveniente para la experimentación local porque no hay:

• demonio de servidor separado;

• punto final HTTP;

• configuración de puerto;

• capa de autenticación adicional.

Una consecuencia importante es que un servidor MCP stdio no debe escribir salida de depuración arbitraria en stdout.

stdout pertenece al protocolo MCP.

Usa stderr para diagnósticos en su lugar.

Por ejemplo:

print("debug information", file=sys.stderr)

o en TypeScript:

console.error("debug information");

El Harness del Agente

La lógica esencial del harness es:

while True:
    response = await model(...)

    calls = find_tool_calls(response)

    if not calls:
        return

    for call in calls:
        result = await mcp.call_tool(
            call.name,
            call.arguments,
        )

        add_result_to_context(result)

Un harness real puede implementar adicionalmente:

permissions
timeouts
tool allowlists
human approval
rate limits
cost limits
logging
tracing
context pruning
retry policies
authentication
authorization
sandboxing
validation
auditing
error recovery

Esta demostración hace intencionalmente muy poco de eso.

Descubrimiento de Herramientas

El harness no necesita una lista codificada de implementaciones.

En su lugar, pregunta al servidor MCP por sus herramientas disponibles.

Conceptualmente:

MCP server
    |
    | tools/list
    v
Agent harness

El harness luego expone el resultado:

name
description
input schema

al modelo.

Si el servidor MCP añade otra herramienta más tarde, el harness puede descubrirla sin añadir otra rama de despacho personalizada.

Ese es uno de los principales beneficios arquitectónicos que proporciona MCP.

La Selección de Herramientas No Está Garantizada

Este punto es importante.

Supongamos que el servidor proporciona:

contact_scott

con una descripción que dice que debe usarse cuando alguien quiera contratar o contactar a Scott.

Un usuario podría decir:

Can I hire Scott for consulting?

El comportamiento deseado del modelo es:

contact_scott(...)

Pero un LLM puede producir en su lugar una respuesta conversacional ordinaria.

MCP no resuelve ese problema.

La decisión:

Does this natural-language request imply this tool?

sigue siendo una inferencia probabilística del modelo.

Las descripciones de herramientas mejoran el comportamiento de enrutamiento, pero no crean garantías formales.

Si una acción debe ocurrir de manera determinista, ese requisito debe aplicarse en la lógica de aplicación ordinaria en lugar de depender únicamente de una instrucción del LLM.

Por Qué Esto Importa

Una vez que el modelo solicita una herramienta, el resto del sistema puede ser determinista:

model requests tool
        |
        v
validate arguments
        |
        v
check permission
        |
        v
execute function
        |
        v
return result

Pero la decisión semántica inicial puede seguir siendo probabilística.

Esta distinción es particularmente importante para acciones con consecuencias como:

sending money
deleting data
changing permissions
submitting legal information
making purchases
sending messages
altering customer records

Un sistema de producción debe colocar controles deterministas explícitos alrededor de acciones con consecuencias significativas.

Transmisión en Streaming

El CLI de Python utiliza streaming para que el texto aparezca mientras se genera.

Sin streaming:

You> explain virtual memory

<wait>

Assistant> Virtual memory is...

Con streaming:

You> explain virtual memory

Assistant> Virtual memory is...

El streaming mejora principalmente la latencia percibida.

Los turnos que utilizan herramientas pueden llevar más tiempo porque pueden requerir múltiples solicitudes al modelo:

model request
    |
    v
tool call
    |
    v
MCP execution
    |
    v
tool result
    |
    v
second model request

Código de Demostración — No Código de Producción

Este repositorio es intencionalmente mínimo.

No proporciona las salvaguardas esperadas de un sistema de agente de producción.

Entre otras cosas, el código de producción necesitaría considerar:

• autenticación;

• autorización;

• gestón de secretos;

• entradas de herramients hostiles;

• inyeción de prompt;

• validación de salida;

• validación de resultdos de herramients;

• apliación de esquemas;

• límit de recursoss; n* aislamiento de red;

• seguriad de subprocso;

• confirmación del usuario para operacions con consecuencias;

• registo de audiotría;

• comportamient de reintentos; n* recuperción de fallos;

• control de costes;

• crecimient del context;

• camios de versión del modelo;

• camios de versión de la API;

• fijación de dependencias;

• observabilidad;

• pruebas y evaluación;

• privacidad y requisitos de retención de datos.

No expongas el servior MCP de ejemplo directament a usuarios no confiables ni uses el patrón de ejemplo contact_scott para comunicacions reales sin añadir validación, autenticación, persistencia, protección contra abusos y manejo de errors adecuados.

De nuevo:

Este repositorio es código de demostración destinado al aprendizaje y la experimentación, no al despliegue en producción.

MCP No Es el Agente

Es útil mantener las capas separadas:

MCP
    != LLM

MCP
    != agent

MCP
    != tool-selection logic

MCP
    != security policy

MCP es el protocolo utilizado para exponer e invocar capacidades.

El harness gestiona el bucle modelo/herramientas.

El modelo realiza la inferencia del lenguaje.

Las herramientas subyacentes realizan el trabajo real.

Un modelo mental útil es:

Agent System
=
Model
+
Harness
+
Tools
+
Context
+
Policy

MCP proporciona una interfaz estándar entre algunos de esos componentes.

¿Por Qué No Simplemente Llamar Funciones Directamente?

Para tres funciones locales en una aplicación, absolutamente puedes.

Por ejemplo:

TOOLS = {
    "foo": foo,
    "bar": bar,
}

puede ser más simple que MCP.

MCP se vuelve más interesante cuando las capacidades necesitan ser reutilizables en múltiples clientes:

                    MCP Server
                   /    |     \
                  /     |      \
                 /      |       \
            CLI agent  IDE    website

El proveedor de herramientas se vuelve independiente de cualquier host o aplicación de modelo en particular.

Esa es la principal razón arquitectónica para introducir MCP.

Experimentos Sugeridos

Una vez que el CLI básico funciona, experimentos útiles incluyen:

run the same prompt repeatedly
change tool descriptions
change models
change system instructions
record selected tools
measure latency
measure token usage
add approval gates
add deliberately ambiguous prompts
add multiple MCP servers
introduce tool failures
introduce malformed results
limit maximum agent steps

Una prueba particularmente útil es registrar:

prompt
selected tool
arguments
number of model calls
latency
final response

a través de ejecuciones repetidas.

Eso permite examinar cuánta variación proviene del modelo y cuánto comportamiento puede ser controlado por el harness.

Licencia

Agrega la licencia que sea apropiada para tu repositorio.

Nota Final

El propósito de este código no es proporcionar otro marco de agente grande.

Es exponer la maquinaria con suficiente claridad para que se pueda entender el proceso central:

Model proposes.
Harness controls.
MCP connects.
Tools execute.

Todo lo más sofisticado se construye sobre eso.