MCP Agent Harness Demo

Eine minimale Demonstration eines LLM-Agent-Harness unter Verwendung des Model Context Protocol (MCP).

Dieses Repository enthält kleine Node.js/TypeScript- und Python-Beispiele, die zeigen, wie ein Agent Folgendes kann:

• Werkzeuge von einem MCP-Server entdecken;

• diese Werkzeuge einem LLM bereitstellen;

• das Modell Werkzeugaufrufe anfordern lassen;

• diese Aufrufe über MCP ausführen;

• Werkzeugergebnisse an das Modell zurückgeben;

• die Schleife fortsetzen, bis das Modell eine endgültige Antwort erzeugt.

Wichtig: Dies ist nur Demonstrationscode. Es ist kein Produktionscode und sollte nicht als sicheres, gehärtetes oder vollständiges Agent-Framework behandelt werden.

Der Zweck des Repositorys ist es, die Mechanismen eines MCP-basierten Agent-Harness leicht inspizierbar zu machen.

Architektur

Auf hoher Ebene:

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

Die Verantwortlichkeiten sind bewusst getrennt:

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 entscheidet nicht, welches Werkzeug aufgerufen werden soll.

Die Werkzeugauswahl bleibt eine Modellentscheidung, sofern die umgebende Anwendung sie nicht explizit einschränkt oder überschreibt.

Related MCP server: MCP Server Scaffold

Warum dieses Repository existiert

Viel Terminologie aus Agent-Frameworks kann verschleiern, was tatsächlich passiert.

Die wesentliche Harness-Schleife ist kaum mehr als:

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

Dieses Repository hält diesen Mechanismus sichtbar, anstatt ihn hinter einem großen Agent-Framework zu verstecken.

Repository-Struktur

Eine typische Struktur ist:

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

Die genauen Verzeichnisnamen können geändert werden, ohne die Architektur zu beeinträchtigen.

Beispiel-MCP-Werkzeuge

Der Demo-Server bietet drei bewusst einfache hypothetische Werkzeuge:

get_github_activity
get_site_content
contact_scott

Dies sind nur Beispiele, die Folgendes demonstrieren sollen:

• Werkzeugerkennung;

• Werkzeug-Schemas;

• Werkzeugbeschreibungen;

• Argumente;

• Ausführung;

• Ergebnisbehandlung.

Sie sollen kein reales Backend darstellen.

Node.js / TypeScript

Voraussetzungen

• Node.js 20+

• ein OpenAI-API-Schlüssel

Abhängigkeiten installieren:

npm install

API-Schlüssel festlegen:

export OPENAI_API_KEY="sk-..."

Den Agent ausführen:

npm start

Der MCP-Server wird vom Agent automatisch über den stdio-Transport gestartet.

Sie sollten den Server nicht separat ausführen müssen.

Beispielausgabe:

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

Voraussetzungen

• Python 3.10+

• ein OpenAI-API-Schlüssel

Eine virtuelle Umgebung erstellen:

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

Paketierungswerkzeuge aktualisieren:

python3 -m pip install --upgrade pip setuptools wheel

Abhängigkeiten installieren:

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

API-Schlüssel festlegen:

export OPENAI_API_KEY="sk-..."

Ausführen:

python3 agent.py

Die Python-Version läuft als interaktiver CLI-Chatbot:

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...

Der Python-Client behält den Konversationsverlauf zwischen den Runden bei und streamt normale Antworten an das Terminal.

Stdio-Transport

Diese Beispiele verwenden MCP über stdio.

Der Agent startet den MCP-Server als untergeordneten Prozess:

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

Dies ist praktisch für lokale Experimente, weil es:

• keinen separaten Server-Daemon;

• keinen HTTP-Endpunkt;

• keine Portkonfiguration;

• keine zusätzliche Authentifizierungsschicht

gibt.

Eine wichtige Konsequenz ist, dass ein MCP-stdio-Server keine beliebigen Debug-Ausgaben an stdout schreiben darf.

stdout gehört zum MCP-Protokoll.

Verwenden Sie stattdessen stderr für Diagnosen.

Zum Beispiel:

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

oder in TypeScript:

console.error("debug information");

Der Agent-Harness

Die wesentliche Harness-Logik ist:

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)

Ein echter Harness kann zusätzlich Folgendes implementieren:

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

Dieses Demo tut davon bewusst sehr wenig.

Werkzeugerkennung

Der Harness benötigt keine hartcodierte Liste von Implementierungen.

Stattdessen fragt er den MCP-Server nach seinen verfügbaren Werkzeugen.

Konzeptionell:

MCP server
    |
    | tools/list
    v
Agent harness

Der Harness stellt dann die resultierenden:

name
description
input schema

dem Modell bereit.

Wenn der MCP-Server später ein weiteres Werkzeug hinzufügt, kann der Harness es erkennen, ohne einen weiteren benutzerdefinierten Dispatch-Zweig hinzuzufügen.

Das ist einer der wichtigsten architektonischen Vorteile, die MCP bietet.

Werkzeugauswahl ist nicht garantiert

Dieser Punkt ist wichtig.

Angenommen, der Server stellt Folgendes bereit:

contact_scott

mit einer Beschreibung, die besagt, dass es verwendet werden soll, wenn jemand Scott einstellen oder kontaktieren möchte.

Ein Benutzer könnte sagen:

Can I hire Scott for consulting?

Das gewünschte Modellverhalten ist:

contact_scott(...)

Aber ein LLM könnte stattdessen eine gewöhnliche Konversationsantwort erzeugen.

MCP löst dieses Problem nicht.

Die Entscheidung:

Does this natural-language request imply this tool?

ist weiterhin probabilistische Modellinferenz.

Werkzeugbeschreibungen verbessern das Routing-Verhalten, schaffen aber keine formalen Garantien.

Wenn eine Aktion deterministisch erfolgen muss, sollte diese Anforderung in gewöhnlicher Anwendungslogik durchgesetzt werden, anstatt sich nur auf eine LLM-Anweisung zu verlassen.

Warum das wichtig ist

Sobald das Modell ein Werkzeug anfordert, kann der Rest des Systems deterministisch sein:

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

Aber die anfängliche semantische Entscheidung kann weiterhin probabilistisch sein.

Diese Unterscheidung ist besonders wichtig für folgenreiche Aktionen wie:

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

Ein Produktionssystem sollte explizite deterministische Kontrollen um Aktionen mit bedeutsamen Konsequenzen platzieren.

Streaming

Die Python-CLI verwendet Streaming, sodass Text erscheint, während er erzeugt wird.

Ohne Streaming:

You> explain virtual memory

<wait>

Assistant> Virtual memory is...

Mit Streaming:

You> explain virtual memory

Assistant> Virtual memory is...

Streaming verbessert in erster Linie die wahrgenommene Latenz.

Runden mit Werkzeugnutzung können dennoch länger dauern, da sie mehrere Modellanfragen erfordern können:

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

Demo-Code — kein Produktionscode

Dieses Repository ist bewusst minimal.

Es bietet nicht die Sicherheitsvorkehrungen, die von einem Produktions-Agent-System erwartet werden.

Unter anderem müsste Produktionscode Folgendes berücksichtigen:

• Authentifizierung;

• Autorisierung;

• Geheimnisverwaltung;

• feindliche Werkzeugeingaben;

• Prompt-Injection;

• Ausgabevalidierung;

• Werkzeug-Ergebnisvalidierung;

• Schema-Durchsetzung;

• Ressourcenlimits;

• Netzwerkisolierung;

• Subprozess-Sicherheit;

• Benutzerbestätigung für folgenreiche Operationen;

• Audit-Protokollierung;

• Wiederholungsverhalten;

• Fehlerwiederherstellung;

• Kostenkontrollen;

• Kontextwachstum;

• Modellversionsänderungen;

• API-Versionsänderungen;

• Abhängigkeits-Pinning;

• Beobachtbarkeit;

• Tests und Evaluierung;

• Datenschutz- und Aufbewahrungsanforderungen.

Setzen Sie den Beispiel-MCP-Server nicht direkt unvertrauenswürdigen Benutzern aus und verwenden Sie das Beispiel contact_scott-Muster nicht für echte Kommunikation, ohne geeignete Validierung, Authentifizierung, Persistenz, Missbrauchsschutz und Fehlerbehandlung hinzuzufügen.

Noch einmal:

Dieses Repository ist Democode für Lernen und Experimentieren, nicht für den Produktionseinsatz.

MCP ist nicht der Agent

Es ist nützlich, die Ebenen getrennt zu halten:

MCP
    != LLM

MCP
    != agent

MCP
    != tool-selection logic

MCP
    != security policy

MCP ist das Protokoll, das verwendet wird, um Fähigkeiten bereitzustellen und aufzurufen.

Der Harness verwaltet die Modell-/Werkzeug-Schleife.

Das Modell führt Sprachinferenz durch.

Die zugrunde liegenden Werkzeuge erledigen die eigentliche Arbeit.

Ein nützliches mentales Modell ist:

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

MCP bietet eine standardisierte Schnittstelle zwischen einigen dieser Komponenten.

Warum nicht einfach Funktionen direkt aufrufen?

Für drei lokale Funktionen in einer Anwendung können Sie das absolut tun.

Zum Beispiel:

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

kann einfacher sein als MCP.

MCP wird interessanter, wenn Fähigkeiten über mehrere Clients hinweg wiederverwendbar sein müssen:

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

Der Werkzeuganbieter wird unabhängig von einem bestimmten Modell-Host oder einer bestimmten Anwendung.

Das ist der wichtigste architektonische Grund, MCP einzuführen.

Vorgeschlagene Experimente

Sobald die grundlegende CLI funktioniert, sind nützliche Experimente:

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

Ein besonders nützlicher Test ist es, Folgendes aufzuzeichnen:

prompt
selected tool
arguments
number of model calls
latency
final response

über wiederholte Läufe hinweg.

Das ermöglicht es zu untersuchen, wie viel Variation vom Modell stammt und wie viel Verhalten durch den Harness kontrolliert werden kann.

Lizenz

Fügen Sie die Lizenz hinzu, die für Ihr Repository geeignet ist.

Abschließende Anmerkung

Der Zweck dieses Codes ist nicht, ein weiteres großes Agent-Framework bereitzustellen.

Es geht darum, die Mechanik klar genug offenzulegen, sodass der Kernprozess verstanden werden kann:

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

Alles Raffiniertere baut darauf auf.