Tutorial · KI-Agenten in Social Media

Einen MCP-Server bauen: Tools, Transport und der erste Client-Aufruf

Von Antoine Blanco··7 Min. Lesezeit

Ein MCP-Server ist ein Programm, das auf tools/list mit einer Liste von Tools antwortet und auf tools/call, indem es eines ausführt. Mit dem Python-SDK sind das zwölf Zeilen. Alles unten lief heute, am 20. November 2026, auf mcp 2.3.0 gegen Protokollrevision 2026-07-28, rohe Ausgabe inklusive.

Was ein MCP-Server beantworten muss

Drei Dinge, und nur das erste ist Pflicht.

Ein Server deklariert Capabilities (tools, resources, prompts), antwortet auf tools/list mit einem deterministischen Satz von Tool-Definitionen, und antwortet auf tools/call, indem er eines ausführt und Inhalt zurückgibt. Resources und Prompts sind optional. Die meisten Server, die sich zu schreiben lohnen, sind ein Sack voll Tools und sonst nichts.

Eine Tool-Definition braucht einen name, eine description und ein inputSchema, das ein gültiges JSON-Schema-Objekt ist. title, outputSchema und annotations sind optional. Die Tools-Spezifikation sagt, Namen sollten 1 bis 128 Zeichen aus Buchstaben, Ziffern, Unterstrich, Bindestrich und Punkt haben und innerhalb des Servers eindeutig sein. Für ein Tool ohne Argumente lautet das empfohlene Schema {"type": "object", "additionalProperties": false}, niemals null.

Einen MCP-Server mit dem MCP-Python-SDK bauen

Installiere das SDK und sein CLI-Extra:

pip install "mcp[cli]"      # or: uv add "mcp[cli]"

Das ist mcp 2.3.0, am 2. Oktober 2026 auf PyPI veröffentlicht. Der Einstiegspunkt ist MCPServer, der den alten Namen FastMCP ersetzt hat:

from mcp.server import MCPServer

mcp = MCPServer("word-count", version="1.0.0")


@mcp.tool()
def count_words(text: str) -> int:
    """Count the words in a block of text."""
    return len(text.split())


if __name__ == "__main__":
    mcp.run()

Drei Dinge passieren, ohne dass du sie schreibst. Aus dem Docstring wird die description des Tools, das Einzige, was das Modell liest, um über einen Aufruf zu entscheiden: schreib sie für das Modell und nicht für deine Kollegen. Aus den Typ-Hints wird das inputSchema. Und aus der Rückgabe-Annotation wird ein outputSchema, sodass das Ergebnis als strukturiertes JSON ankommt und nicht nur als Text.

Teste ihn, bevor du irgendeinen Client anschließt:

mcp dev server.py

Das öffnet den MCP Inspector, der die Tools auflistet und sie dich von Hand aufrufen lässt. Es ist der schnellste Weg, um zu merken, dass ein Argumentname, den du für offensichtlich hieltest, es nicht ist.

stdio oder Streamable HTTP

mcp.run() nutzt standardmäßig stdio. Die Revision 2026-07-28 definiert genau zwei Standardtransporte, und die Wahl dreht sich darum, wer den Prozess startet, nicht um Funktionen: die Protokollsemantik ist auf jedem Transport identisch.

stdio Streamable HTTP
Wer ihn startet der Client, als Subprozess du, als Service
Framing zeilenweise getrenntes JSON-RPC auf stdin und stdout ein HTTP-POST pro Nachricht
Erreicht andere Leute nein ja
Authentifizierung erbt den lokalen Prozess OAuth oder ein API-Key
Abbruch notifications/cancelled der Client schließt den Stream
Geeignet für ein Tool auf deiner eigenen Maschine alles, was andere Leute nutzen

Eine Regel, die jeder am ersten Tag bricht: bei stdio gehört stdout dem Protokoll. Ein verirrtes print() zerstört den Stream. Logge auf stderr.

Wechsle den Transport mit einem einzigen Argument:

mcp.run(transport="streamable-http")
INFO  StreamableHTTP session manager started
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Der Endpunkt ist /mcp, also http://127.0.0.1:8000/mcp.

Der erste Client-Aufruf, echt

Richte den eigenen Client des SDK auf den stdio-Server:

import asyncio, sys
from mcp import Client, StdioServerParameters

async def main():
    params = StdioServerParameters(command=sys.executable, args=["server.py"])
    async with Client(params) as client:
        print("protocol:", client.protocol_version)
        tools = await client.list_tools()
        for t in tools.tools:
            print("tool:", t.name, "|", t.description)
        res = await client.call_tool("count_words", {"text": "one two three four"})
        print("content:", res.content)
        print("structured:", res.structured_content)

asyncio.run(main())

Was es ausgab:

protocol: 2026-07-28
tool: count_words | Count the words in a block of text.
content: [TextContent(type='text', text='4', annotations=None, meta=None)]
structured: {'result': 4}

Achte auf die zwei Schreibweisen. Das Format auf der Leitung ist camelCase (inputSchema, structuredContent, isError) ; die Python-Objekte in snake_case (input_schema, structured_content, is_error). Wer t.inputSchema liest, bekommt einen AttributeError, und genau da habe ich meine ersten fünf Minuten verloren.

Über HTTP braucht curl vier Header, und sie falsch zu setzen ist die ganze Debugging-Sitzung:

curl -s -X POST http://127.0.0.1:8000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'mcp-method: tools/list' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{
       "io.modelcontextprotocol/protocolVersion":"2026-07-28",
       "io.modelcontextprotocol/clientCapabilities":{}}}}'
{"jsonrpc":"2.0","id":1,"result":{"cacheScope":"private","resultType":"complete",
 "tools":[{"description":"Count the words in a block of text.",
 "inputSchema":{"type":"object","properties":{"text":{"title":"Text","type":"string"}},
 "required":["text"],"title":"count_wordsArguments"},"name":"count_words",
 "outputSchema":{"properties":{"result":{"title":"Result","type":"integer"}},
 "required":["result"],"type":"object"}}],"ttlMs":0}}

Zwei Fehler wirst du in dieser Reihenfolge treffen. Lass _meta weg, und du bekommst -32602: params._meta must be an object carrying the required 'io.modelcontextprotocol/protocolVersion' and 'io.modelcontextprotocol/clientCapabilities' envelope keys. Lass _meta drin, aber vergiss den Header, und du bekommst -32020: mcp-method header does not match the request body's method. Ein tools/call braucht einen dritten, mcp-name, der den Namen des Tools trägt, sonst kommt derselbe -32020 zurück.

Mit allen zusammen gibt der Aufruf beide Formen zurück:

{"id":2,"result":{"content":[{"text":"4","type":"text"}],"isError":false,
 "resultType":"complete","structuredContent":{"result":4}}}

Was die Revision 2026-07-28 geändert hat

Wenn du einem Tutorial folgst, das für 2025-06-18 oder 2025-11-25 geschrieben wurde, haben sich drei Dinge verschoben.

Es gibt keinen initialize-Handshake mehr. Jede Anfrage deklariert ihre eigene Protokollversion und die Client-Capabilities in params._meta, und der Server nimmt jede Anfrage einzeln an oder lehnt sie ab. Streamable HTTP spiegelt diese Werte in Header, damit ein Proxy ohne Blick in den Body routen kann, und der Body bleibt die Quelle der Wahrheit.

Discovery ist ein einziger optionaler Aufruf. server/discover gibt die unterstützten Versionen, die Capabilities und die Identität in einem Zug zurück:

{"id":3,"result":{"capabilities":{"prompts":{"listChanged":true},
 "resources":{"listChanged":true,"subscribe":true},"tools":{"listChanged":true}},
 "supportedVersions":["2026-07-28"]}}

Und es gibt keine Protokoll-Session mehr. Ein Server kann keinen Zustand pro Verbindung halten, also muss alles, was mehrere Aufrufe überspannt, ein explizites Handle sein, das du aus einem Tool zurückgibst und beim nächsten als Argument annimmst. Schick eine Anfrage im alten Stil an diesen Server, und er fällt auf den Session-Pfad zurück, der antwortet: Bad Request: Missing session ID. Das ist Rückwärtskompatibilität, die funktioniert, kein Bug. Was das für das Deployment bedeutet, steht in MCP-Server-Hosting.

Der Fehlerpfad, der das Modell lernen lässt

Die Spezifikation teilt Fehler in zwei. Eine fehlerhafte Anfrage oder eine unbekannte Methode ist ein JSON-RPC-Fehler. Ein Fehlschlag, den das Modell durch einen anderen Versuch beheben könnte, ist ein Tool-Ergebnis mit isError: true, weil Clients diese an das Modell zurückgeben und es sich selbst korrigieren kann.

Das SDK macht das fast von allein richtig. Ein unbekanntes Tool gibt ein Ergebnis zurück, keinen Protokollfehler:

{"id":4,"result":{"content":[{"text":"Unknown tool: nope","type":"text"}],"isError":true}}

Aber wirf eine Exception innerhalb eines Tools, und die Nachricht wird verschluckt:

raise ValueError("text is empty, pass at least one word")
is_error: True
content: Error executing tool count_words

Das Modell weiß jetzt, dass der Aufruf fehlgeschlagen ist, und nichts darüber, warum, also versucht es es mit denselben Argumenten erneut. Wenn du willst, dass sich das Modell selbst korrigiert, gib die Erklärung als eigenen Text des Tools zurück, statt eine Exception zu werfen. Diese eine Angewohnheit ist mehr wert als jede Schema-Arbeit.

Bevor du einen Agenten daran lässt

Ein Server, der auf deinem Laptop läuft, ist kein Server, den du jemand anderem in die Hand gibst. Zwei Teile fehlen, und jedes hat hier seine eigene Seite: die Authentifizierung, behandelt in OAuth für einen MCP-Server, und die Hosting-Entscheidung. Beim Rest ist die Spezifikation unmissverständlich: validiere jede Eingabe, begrenze die Aufrufrate, und markiere niemals ein Secret mit x-mcp-header, weil der Wert eines Headers für jeden Zwischenknoten auf dem Weg sichtbar ist.

Es lohnt sich auch zu fragen, ob du den Server überhaupt schreiben solltest. Bei etwas wie Social Publishing ist nicht MCP das Schwere, sondern acht Plattform-APIs, acht OAuth-Flows und das Erneuern der Tokens: deshalb betreibt PlugKit einen gehosteten MCP-Server auf https://api.plugkit.co/mcp, statt eine Vorlage auszuliefern, für 49 $ pro Monat für 5 verbundene Konten, jederzeit kündbar, oder 97 $ pro Monat für 30, nach sieben kostenlosen Tagen mit Karte bei der Anmeldung und ohne Abbuchung vor Tag 7. Geprüft am 20. November 2026. Schreib deinen eigenen, wenn die Tools deine sind: deine Datenbank, deine interne API, dein Build-System. MCP oder REST-API für deinen Agenten ist die Entscheidung eine Ebene darüber, und Instagram-MCP-Server zeigt, wie das fertige Ding von der Client-Seite aussieht.

FAQ

In welcher Sprache sollte ich einen MCP-Server bauen?

In der, in der deine Tools schon leben. Die offizielle SDK-Liste hat zehn: TypeScript, Python, C#, Go, Rust und Ruby in Tier 1, Java in Tier 2, Swift, PHP und Kotlin in Tier 3, wobei der Tier sagt, wie vollständig und wie gepflegt eines ist. Sie sprechen alle dasselbe JSON-RPC. Der Server ist eine dünne Hülle um Code, den du schon hast, diesen Code in eine andere Sprache umzuschreiben ist also der teure Fehler.

Brauche ich Streamable HTTP, oder reicht stdio?

stdio reicht, wenn du der einzige Nutzer auf dieser Maschine bist: der Client startet dein Skript als Subprozess und nichts ist exponiert. Sobald eine zweite Person oder ein gehosteter Agent es braucht, brauchst du Streamable HTTP, eine URL und Authentifizierung.

Wie teste ich einen MCP-Server ohne Client?

mcp dev server.py öffnet den MCP Inspector, der deine Tools auflistet und sie mit den Argumenten aufruft, die du eintippst. Danach zeigt curl gegen den HTTP-Endpunkt genau das JSON, das ein echter Client sendet, und so erwischst du ein Schema, das das Modell falsch lesen wird.

Warum funktioniert mein Tool im Inspector, aber nicht im Agenten?

Meist die Beschreibung. Das Modell wählt Tools, indem es description und die Argumenttitel liest, und ein Docstring wie "macht die Sache" gibt ihm nichts, woran es anknüpfen kann. Schreib den Docstring als Anweisung um, sag, was das Tool zurückgibt, und benenne Argumente so, wie ein Aufrufer sie erraten würde.

Wie viele Tools sollte ein MCP-Server bereitstellen?

Weniger, als du möchtest. Jede Definition liegt in jedem Zug im Kontext des Modells, hundert Tools kosten also echte Tokens und echte Verwechslungen zwischen Fast-Dubletten. Gruppiere nach Aufgabe, gib strukturierten Inhalt zurück, damit ein Tool mehrere Fragen beantwortet, und teile in mehrere Server auf, bevor du einen Server in hundert Namen zerlegst.

AB
Antoine BlancoGründer von PlugKit. Betreibt seine eigenen Instagram-, YouTube- und X-Accounts über die hier beschriebene API und den MCP-Server.

Ein Plug für jede Plattform, die dein Agent anfasst

49 $ im Monat für 5 verbundene Accounts, jederzeit kündbar. Jede Funktion in jedem Tarif.

Hol dir deinen API-Key →
Deutsch ▾