MCP vs API: ein Bestellservice, zwei Schnittstellen

Begleit-Repository zum Video „MCP vs API: Warum brauchen wir MCP, wenn REST schon funktioniert?“

Klonen Sie es, führen Sie zwei Befehle aus und erledigen Sie dieselbe Aufgabe zweimal. Einmal mit einer einfachen REST-API. Einmal mit einem MCP-Server darauf. Dauert etwa 20 Minuten.

Was wir bauen

Du betreibst einen kleinen Online-Shop. Bestellungen kommen herein. Einige bleiben hängen und werden nie versendet. Du möchtest, dass ein KI-Agent die hängengebliebenen findet und für jede ein GitHub-Issue eröffnet.

Das ist das gesamte Beispiel. Eine kleine, echte Aufgabe.

Der erste Weg: Du gibst dem Agenten deine API-Dokumentation und lässt ihn curl verwenden. Er muss herausfinden, welchen Endpunkt er aufrufen soll, einen Datumsfilter für „mehr als 7 Tage“ erstellen, bemerken, dass die Antwort in Seiten kommt, und Cent in Dollar umrechnen.

Der zweite Weg: Du gibst ihm ein Tool namens find_stale_orders, das { older_than_days: 7 } entgegennimmt.

Beide rufen denselben Endpunkt auf, GET /orders. Der Shop ändert sich überhaupt nicht. Was sich ändert, ist, wer das Denken übernimmt: der Agent oder dein Server.

                        ┌──────────────────────────────────┐
  Web frontend  ───────▶│                                  │
  Mobile app    ───────▶│   Orders service (Express)       │
  Microservice  ───────▶│   GET  /orders                   │
                        │   GET  /orders/:id               │
                        │   PATCH /orders/:id              │
                        └──────────────▲───────────────────┘
                                       │  plain HTTP, nothing AI specific
                        ┌──────────────┴───────────────────┐
  Claude Code   ───────▶│   Orders MCP server              │
  Cursor        ───────▶│   tool: find_stale_orders        │
  Codex         ───────▶│   input: { older_than_days: 7 }  │
                        └──────────────────────────────────┘

Deine API ist die Tür. MCP gibt KI-Clients einen standardisierten Griff, um sie zu öffnen.

Der Bestellservice weiß nie, dass Claude Code existiert. Der MCP-Server ist nur ein weiterer HTTP-Client deiner API. Der einzige Unterschied ist, dass er sich selbst so beschreibt, dass Agenten es verstehen.

Related MCP server: OHMS

Probier es in einer Minute aus

Du brauchst Node 20 oder neuer. Sonst nichts. Keine Datenbank, keine API-Schlüssel.

git clone https://github.com/bytemonk-academy/mcp-vs-api.git
cd mcp-vs-api
npm install
npm test

npm test führt 31 Tests gegen sowohl die REST-API als auch den MCP-Server aus. Wenn sie bestehen, funktioniert alles und der Rest ist nur, dass du zusiehst, wie es passiert.

Starte nun den Dienst und lass ihn laufen:

npm run api

In einem zweiten Terminal schau dir die Daten an:

npm run orders

  ID         CUSTOMER             STATUS      PLACED       DAYS  TOTAL
  ----------------------------------------------------------------------
  ORD-1001   Ada Lovelace         UNSHIPPED   2026-07-27   31    $129.00
  ORD-1002   Grace Hopper         UNSHIPPED   2026-08-03   24    $45.99
  ...

  Showing 20 of 24 matching orders.

  !! There are more. page.nextOffset = 20
     You have NOT seen all 24 orders.

Dann stelle ihm die Frage, um die es in dieser gesamten Demo geht:

npm run orders -- --stale=7

Acht Bestellungen. Dieselben acht auf jeder Maschine, zu jeder Tageszeit.

Was ist npm run orders?

Es ist eine Abkürzung für curl.

Es sendet GET /orders an deine API und gibt die Antwort als Tabelle statt als rohes JSON aus. Das ist alles, was es tut. Du kannst dieselbe Anfrage selbst ausführen:

curl "http://localhost:3000/orders"

Du bekommst dieselben Daten, nur schwerer zu lesen. Das Skript ist nur da, damit du die Daten schnell prüfen kannst. Es ist nicht Teil der Lektion. In Phase 1 bekommt der Agent curl und die Dokumentation, sonst nichts.

Es akzeptiert ein paar Optionen:

npm run orders -- --stale=7             # unshipped for more than 7 days
npm run orders -- --status=UNSHIPPED    # filter by status
npm run orders -- --limit=5 --offset=5  # move through the pages by hand

Warum die Testdaten so aussehen, wie sie aussehen

Es gibt 24 Bestellungen, die im Speicher gehalten werden, mit Daten, die relativ zu heute gesetzt sind. So gibt es immer genau 8 veraltete Bestellungen, wann immer du dies klonst.

Drei Probleme sind absichtlich eingebaut, damit du den Unterschied selbst sehen kannst, statt dem Video zu glauben:

• Die Antwort kommt in Seiten. Frag nach Bestellungen und du bekommst 20 von 24. Nichts in diesen 20 Zeilen sieht unvollständig aus. Ein Agent, der bei der ersten Seite aufhört, gibt eine falsche Antwort und klingt dabei überzeugt.

• Einige alte Bestellungen sind storniert. Sie sehen veraltet aus, sind es aber nicht. Wenn du nach shippedAt statt nach status filterst, zählst du sie fälschlicherweise mit.

• Einige Bestellungen liegen knapp unter der 7-Tage-Linie. Zähle die Tage leicht falsch und du bekommst eine falsche Gesamtzahl, keine Fehlermeldung.

Der MCP-Server behandelt alle drei im Code, einmal, in src/mcp/server.ts. In der curl-Version muss der Agent alle drei jedes Mal richtig hinbekommen.

Die Übung

Mach diese in Reihenfolge. Phase 1 vor Phase 2 ist der Punkt, denn der Unterschied ist die Lektion.

Außerdem hier: die API-Referenz, die du dem Agenten in Phase 1 gibst, Prompts, die du kopieren kannst, und Fehlerbehebung.

Phase 2 eröffnet echte GitHub-Issues, also verwende ein Test-Repository, das du nicht schlimm findest, wenn es voll wird.

Was hier drin ist

src/
  data/orders.ts     The 24 test orders
  api/app.ts         The REST API. Knows nothing about MCP.
  api/server.ts      Starts it on a port.
  mcp/server.ts      The MCP server. Calls the REST API over HTTP.
scripts/orders.ts    The table viewer used above
clients/             Plain MCP clients, in Python and TypeScript
tests/               Tests for both halves
docs/                The walkthrough
.mcp.json            Claude Code reads this automatically
.cursor/mcp.json     Cursor reads this automatically

Drei Tools. Jedes ist ein dünner Wrapper um einen Endpunkt, den du bereits hast:

src/mcp/server.ts ist etwa 170 Zeilen lang und der Großteil davon sind Kommentare. Das ist alles, was ein MCP-Server wirklich ist.

Das Protokoll selbst sehen

Claude Code macht hier nichts Besonderes. Es startet den Server als Unterprozess und sendet JSON-RPC-Nachrichten über stdin und stdout. clients/raw_mcp_client.py macht dasselbe von Hand:

async with stdio_client(server) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        result = await session.call_tool("find_stale_orders", {"older_than_days": 7})

Dasselbe Skript spricht dann über HTTP mit dem MCP-Server von GitHub, um die Issues zu eröffnen:

await session.call_tool("create_issue", {"owner": owner, "repo": name, "title": ...})

Beide Male dieselbe Form. Ein Server ist ein Node-Prozess auf deinem Laptop. Der andere wird von GitHub betrieben. Der Client kann sie nicht unterscheiden. Das ist der Teil, den man sich merken sollte. Es gibt eine TypeScript-Version in clients/, wenn du lieber in einer Sprache bleiben möchtest.

Tests

npm test

31 Tests. Die MCP-Tests steuern einen echten MCP-Client über stdio, genauso wie Claude Code es tut.

Lesenswert, wenn du planst, deinen eigenen Server zu schreiben. Sie zeigen, was wirklich zu prüfen ist: dass jedes Tool eine brauchbare Beschreibung und ein Schema hat, dass Paging wirklich funktioniert, dass eine 404 als Tool-Fehler zurückkommt statt als Absturz, und dass stornierte Bestellungen aus den Ergebnissen herausbleiben.

Befehle

npm run api        # REST API on :3000
npm run api:dev    # same, restarts when you edit a file
npm run orders     # print the orders as a table
npm run mcp        # run the MCP server directly (agents usually do this for you)
npm test           # the tests
npm run typecheck  # tsc --noEmit
npm run inspect    # MCP Inspector, to try the tools by hand

npm run inspect ist der schnellste Weg, um genau zu sehen, was ein Agent sieht: Toolnamen, Beschreibungen und das Eingabeschema für jedes.

Die Daten werden im Speicher gehalten, also setzt ein Neustart von npm run api alles auf den Anfang zurück.

Wann lohnt sich MCP?

Phase 1 funktioniert. Das ist kein Trick. Ein guter Agent wird die veralteten Bestellungen finden und die Issues eröffnen, nur mit curl und deiner Dokumentation. MCP ist nicht das, was die Aufgabe möglich macht.

Was es ändert, ist die Form der Integration. Wie man deinen Bestellservice abfragt, lebt jetzt in einem Server, statt im Kontextfenster jedes Agenten. Dieselbe Fähigkeit funktioniert in Claude Code, Cursor und Codex, ohne für jedes eine neue Integration zu schreiben. Und du entscheidest, welche Fähigkeiten du freigibst, was sich sehr von der Übergabe eines API-Schlüssels unterscheidet.

Was es nicht ändert: Authentifizierung, Autorisierung, Validierung, Ratenbegrenzung, Wiederholungen und gutes Servicedesign sind immer noch deine Aufgabe. Ein MCP-Server auf einer schlecht gestalteten API ist immer noch eine schlecht gestaltete API.

Grob gesagt wächst der Wert mit der Anzahl der Clients multipliziert mit der Anzahl der Tools. Ein Agent, der zwei Funktionen aufruft, die du kontrollierst? Überspringe es, ruf einfach die Funktionen auf. Dreißig Tools über fünf Teams und vier Clients? Dann beginnt sich ein gemeinsames Protokoll auszuzahlen. docs/architecture.md behandelt, wo die Grenze liegt.

MIT-lizenziert. Verwende es in deinem eigenen Unterricht, keine Anerkennung nötig.