Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Implementatie van tools: JSON-schema en handlers

Les 11 van 14 Bijgewerkt op 2 november 2026 Ontwikkelaar
Op deze pagina
  1. De anatomie van een MCP-tool
  2. Wat de decorator voor u bouwt
  3. Eerst benoemen, dan beschrijven
  4. Typen, asynchrone handlers en validatie
  5. De retourwaarde polijsten
  6. Belangrijkste punten

Bijgewerkt op 2 november 2026 — MCP Python SDK v2. Deze cursus volgt nu versie 2 van de mcp-SDK (2.3.0 per 2 oktober 2026): MCPServer vervangt FastMCP, transportinstellingen verhuizen naar run() of streamable_http_app(), en een applicatie die onder een echte hostnaam wordt blootgesteld, moet die hostnaam declareren (transport_security). Dit is ook de versie die vereist is door de Mistral SDK: de mistralai[agents]-extra vereist mcp>=2.2.0,<3.0. Bronnen: Wat is nieuw in v2 · Migratiegids · Implementeren & schalen.

De anatomie van een MCP-tool

Een MCP-tool ziet eruit als een Python-functie, maar vanuit het perspectief van het model is het dat niet. Het is een contract uit vier delen: een naam, een beschrijving, een JSON-invoerschema en een handler die de logica uitvoert. Het model ziet uw code nooit; het ziet alleen dit contract. Een perfect geïmplementeerde tool die slecht wordt beschreven, zal nooit worden aangeroepen, of op het verkeerde moment. De kwaliteit van het contract bepaalt daarom de effectiviteit van de server veel meer dan de kwaliteit van de implementatie.

Wat de decorator voor u bouwt

MCPServer bouwt dit contract automatisch op basis van uw functiesignatuur en docstring. U schrijft standaard Python:

from mcp.server.mcpserver import MCPServer

app = MCPServer("My Server")

@app.tool()
def search_documents(
    query: str,
    max_results: int = 10,
    language: str = "fr",
    include_archived: bool = False,
) -> str:
    """Searches for documents in the knowledge base.

    Args:
        query: Search terms (2-500 characters)
        max_results: Maximum number of results (1-100, default: 10)
        language: ISO 639-1 language code (default: fr)
        include_archived: Include archived documents (default: false)

    Returns:
        JSON with the list of found documents and the total count
    """
    # Search logic
    ...

En het model ontvangt dit:

{
  "name": "search_documents",
  "description": "Searches for documents in the knowledge base.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search terms (2-500 characters)"
      },
      "max_results": {
        "type": "integer",
        "description": "Maximum number of results (1-100, default: 10)",
        "default": 10
      },
      "language": {
        "type": "string",
        "description": "ISO 639-1 language code (default: fr)",
        "default": "fr"
      },
      "include_archived": {
        "type": "boolean",
        "description": "Include archived documents (default: false)",
        "default": false
      }
    },
    "required": ["query"]
  }
}

Vergelijk de twee blokken regel voor regel: elke type-annotatie wordt een JSON-type, elke standaardwaarde wordt een default-veld, elke regel in de Args-sectie wordt een parameterbeschrijving, en het enige argument zonder standaardwaarde belandt in required. Met andere woorden: alles wat u weglaat uit de docstring, verdwijnt volledig uit het contract.

Eerst benoemen, dan beschrijven

De toolnaam is de functienaam, en het model gebruikt deze als eerste aanwijzing. Een werkwoord dat een actie aanduidt, gevolgd door een duidelijk object, laat geen ruimte voor ambiguïteit, terwijl een generieke of technische naam het model dwingt te raden:

# Goed: actie-werkwoord + duidelijk object
@app.tool()
def create_issue(title: str, body: str) -> str: ...

@app.tool()
def search_repositories(query: str) -> str: ...

@app.tool()
def get_user_profile(username: str) -> str: ...

# Slecht: vaag, ambigu, technisch
@app.tool()
def process(data: str) -> str: ...        # Te vaag

@app.tool()
def handle_request(req: str) -> str: ...   # Onbegrijpelijk voor de LLM

@app.tool()
def db_query(sql: str) -> str: ...         # Te technisch

De docstring neemt het vervolgens over en vormt het meest kritieke onderdeel van uw hele server. Deze moet drie vragen beantwoorden, in deze volgorde: wanneer deze tool moet worden gebruikt, welke parameters moeten worden verstrekt met hun formaat en beperkingen, en wat er als resultaat wordt verwacht. Het volgende voorbeeld laat zien hoe dit er in de praktijk uitziet:

@app.tool()
def book_restaurant(
    restaurant_name: str,
    date: str,
    party_size: int,
    special_requests: str = "",
) -> str:
    """Books a table at a restaurant.

    Performs a complete reservation including email
    confirmation. Use this tool when the user wants
    to book a specific restaurant.

    Args:
        restaurant_name: Exact name of the restaurant
        date: Date and time in ISO 8601 format (e.g., 2026-04-15T19:30:00)
        party_size: Number of guests (1-20)
        special_requests: Special requests (allergies, occasion, etc.)

    Returns:
        JSON with the reservation number, confirmation,
        and restaurant details
    """
    ...

De alinea na de eerste regel is wat amateur-servers het vaakst missen. Zonder deze weet het model wel wat de tool doet, maar niet in welke situatie deze moet worden geactiveerd. En het ISO 8601-datumvoorbeeld bespaart u tientallen oproepen met "15 april om 19:30 uur".

Typen, asynchrone handlers en validatie

MCPServer vertaalt veelvoorkomende Python-annotaties naar hun JSON-schema-equivalenten.

PythonJSON-schemaVoorbeeld
strstring"tekst"
intinteger42
floatnumber3.14
boolbooleantrue
list[str]array van string["a", "b"]
dictobject{"sleutel": "waarde"}
Optional[str]string (nullable)"tekst" of null

Zodra een tool buiten zijn eigen proces stapt—netwerkaanroep, databasequery, lezen van extern bestand—declareer deze dan als async. Een synchrone handler die wacht op een HTTP-antwoord blokkeert de hele server, en uw andere gebruikers ook:

import httpx

@app.tool()
async def fetch_api_data(endpoint: str) -> str:
    """Retrieves data from an external API.

    Args:
        endpoint: The API endpoint path (e.g., /users/123)

    Returns:
        JSON data from the API
    """
    async with httpx.AsyncClient() as client:
        response = await client.get(f"https://api.example.com{endpoint}")
        response.raise_for_status()
        return response.text

Het JSON-schema beperkt typen, nooit waarden: niets verhindert het model om een naam van 3.000 tekens of een verzonnen rol te sturen. Valideer daarom altijd bij de ingang van de handler en retourneer een bericht dat aangeeft welke correctie nodig is:

import json

@app.tool()
def create_user(name: str, email: str, role: str = "viewer") -> str:
    """Creates a new user.

    Args:
        name: Full name (2-100 characters)
        email: Valid email address
        role: Role: viewer, editor, admin (default: viewer)

    Returns:
        JSON with the created user details
    """
    # Validation
    if len(name) < 2 or len(name) > 100:
        return json.dumps({"error": "Name must be between 2 and 100 characters"})

    if "@" not in email or "." not in email:
        return json.dumps({"error": "Invalid email address"})

    valid_roles = ("viewer", "editor", "admin")
    if role not in valid_roles:
        return json.dumps({"error": f"Invalid role. Choices: {', '.join(valid_roles)}"})

    # Creation...
    return json.dumps({"success": True, "user": {"name": name, "email": email, "role": role}})

Het derde bericht somt de toegestane waarden op. Het model kan zich dan corrigeren en de tool opnieuw aanroepen, in plaats van op te geven bij een foutmelding “Ongeldige rol” zonder uitleg.

De retourwaarde polijsten

Een MCP-tool retourneert altijd tekst, maar die tekst kan gestructureerde JSON zijn, wat het model zeer goed interpreteert. Het contrast tussen deze twee returns vat het essentiële samen:

# Goed: gestructureerde, leesbare JSON
return json.dumps({
    "success": True,
    "user": {
        "name": "Alice Dupont",
        "email": "[email protected]",
        "role": "editor",
    },
    "message": "User created successfully"
}, ensure_ascii=False)

# Slecht: rauwe data die moeilijk te gebruiken is
return "OK:user_id=abc123:status=created"

Geef altijd de voorkeur aan waarden die leesbaar zijn voor een mens boven interne identificatiecodes: het model kan "Alice Dupont" direct gebruiken in zijn antwoord, terwijl een UUID een extra oproep vereist om uit te zoeken over wie het gaat. Pas daarentegen op voor opgeblazen returns—vijftig velden per record vullen de context zonder waarde toe te voegen. De juiste reflex bij het schrijven van een tool is uzelf afvragen wat het model nodig heeft om de gebruiker te informeren, en alleen dat terug te geven.

Belangrijkste punten

  • De @app.tool()-decorator genereert automatisch het JSON-schema voor parameters
  • De functienaam = toolnaam (werkwoord + object)
  • De docstring is cruciaal: deze leidt het model bij wanneer en hoe de tool moet worden aangeroepen
  • Gebruik Python-type-annotaties voor het schema (str, int, float, bool, list, dict)
  • Valideer altijd invoer en retourneer actiegerichte fouten
  • Retourneer gestructureerde JSON met voor mensen leesbare waarden