De meeste gidsen over het Model Context Protocol (MCP) laten zien hoe je een server installeert die iemand anders heeft geschreven. Deze gids laat zien hoe je je eigen MCP-server bouwt in Python: een kleine server met twee tools die elke AI-app met MCP-ondersteuning kan aanroepen. Je bouwt hem, test hem zonder AI-app, inspecteert hem met de officiële MCP Inspector en koppelt hem daarna aan een editor of assistent.
De belangrijkste punten
- De officiële MCP Python SDK 2.x heeft de serverklasse hernoemd naar MCPServer, waardoor veel oudere tutorials niet meer werken zoals ze geschreven zijn.
- Zet je @mcp.tool() boven een functie, dan wordt die functie een tool; de naam, beschrijving en het invoerschema komen uit je code.
- Test de server in het geheugen met de Client-klasse van de SDK en daarna via stdio met de officiële MCP Inspector.
- Koppel hem aan Cursor, VS Code of Claude Desktop door de app een uv-startcommando met een absoluut pad te geven.
Op 15 november 2026 staat de officiële Python SDK op versie 2.3.0 (uitgebracht op 2 oktober 2026) en MCP Inspector op 2.15.0 (uitgebracht op 12 november 2026). SDK 2.x heeft de belangrijkste serverklasse hernoemd, waardoor veel oudere tutorials niet meer werken zoals ze geschreven zijn. De project-, test- en Inspector-commando’s hieronder zijn met die versies uitgevoerd.
Wat een MCP-server is
MCP is een opensourcestandaard om AI-applicaties te verbinden met externe systemen. Met drie begrippen uit de SDK-documentatie kun je alles volgen:
- Een host is de AI-app waarmee je praat, zoals een chatassistent of een code-editor.
- Een client zit in de host en spreekt MCP.
- Een server is wat jij bouwt. Die kan tools aanbieden (functies die het model aanroept), resources (data die de app laadt) en prompts (sjablonen die de gebruiker kiest).
Deze gids houdt het bij tools. De twee die je schrijft, een woordenteller en een datumcalculator, doen exact werk dat code beter afhandelt dan een schatting van een model.
Wat je nodig hebt
- uv, de Python-projectmanager die in de officiële MCP-tutorial wordt gebruikt. Hij downloadt Python voor je als er nog geen geschikte versie op je computer staat. De SDK heeft Python 3.10 of nieuwer nodig.
- Node.js, alleen voor de Inspector in stap 4. Inspector 2.15.0 vereist Node
^22.23.4 || ^24.22.1 || >=26.12.1. - Een app met MCP-ondersteuning voor stap 5 (optioneel).
Installeer uv op macOS of Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
Op Windows, in PowerShell:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Start daarna je terminal opnieuw, zodat het commando uv gevonden wordt.
In cijfers
2.3.0gebruikte versie van de Python SDK
2.15.0gebruikte versie van MCP Inspector
3.10minimale Python-versie
Stap 1: maak het project aan
uv init --bare handy-tools
cd handy-tools
uv add "mcp[cli]"
--bare maakt alleen een pyproject.toml aan, en meer heeft dit project niet nodig. De extra cli voegt de commandoregeltool mcp toe. Controleer de installatie:
uv run mcp version
Verwachte uitvoer:
MCP version 2.3.0
Stap 2: schrijf de server
Maak in de projectmap een bestand met de naam server.py:
from datetime import date
from mcp.server import MCPServer
from mcp.server.mcpserver.exceptions import ToolError
mcp = MCPServer("Handy Tools")
@mcp.tool()
def count_words(text: str) -> int:
"""Count the words in a piece of text."""
return len(text.split())
@mcp.tool()
def days_between(start: str, end: str) -> int:
"""Count the days from one date to another. Dates use YYYY-MM-DD format."""
try:
first = date.fromisoformat(start)
second = date.fromisoformat(end)
except ValueError:
raise ToolError("Dates must look like 2026-11-15 (YYYY-MM-DD).")
return (second - first).days
if __name__ == "__main__":
mcp.run()
Wat elk onderdeel doet:
MCPServer("Handy Tools")maakt de server aan. In SDK 2.x importeer je hem uitmcp.server.@mcp.tool()maakt van een functie een tool. De SDK haalt de naam van de tool uit de functienaam, de beschrijving uit de docstring en het invoerschema uit de type hints. Je schrijft geen JSON.ToolErrorstuurt een leesbaar bericht terug naar het model, zodat het zijn argumenten kan aanpassen en het opnieuw kan proberen.mcp.run()zonder argumenten start de server via stdio: de host start je bestand als subproces en praat ermee via stdin en stdout.

Stap 3: test hem vanuit Python
De SDK bevat een Client-klasse die in het geheugen verbinding kan maken met je serverobject, zonder subproces, zonder poort en zonder AI. Maak check.py aan naast server.py:
import asyncio
from mcp import Client
from server import mcp
async def main() -> None:
async with Client(mcp) as client:
tools = await client.list_tools()
print([tool.name for tool in tools.tools])
result = await client.call_tool("count_words", {"text": "the quick brown fox"})
print(result.structured_content)
result = await client.call_tool("days_between", {"start": "2026-11-15", "end": "2027-01-01"})
print(result.structured_content)
result = await client.call_tool("days_between", {"start": "tomorrow", "end": "2027-01-01"})
print(result.is_error, result.content[0].text)
asyncio.run(main())
Voer het uit:
uv run check.py
Verwachte uitvoer:
['count_words', 'days_between']
{'result': 4}
{'result': 47}
True Error executing tool days_between: Dates must look like 2026-11-15 (YYYY-MM-DD).
Je ziet ook een INFO-logregel over de mislukte aanroep: dat is de server die de ToolError logt. Merk op dat de ongeldige datum geen exceptie opleverde in de client: een mislukte toolaanroep komt terug als een normaal resultaat met is_error op True.
Wist je dat?
Een mislukte toolaanroep levert geen exceptie op in de client. Hij komt terug als een normaal resultaat met is_error op True, met daarin het bericht van de ToolError.
Stap 4: inspecteer hem met MCP Inspector
MCP Inspector is de eigen testtool van het MCP-project. In de CLI-modus start hij je server zoals een echte host dat zou doen en laat hij zien wat er terugkomt. Vanuit de projectmap:
npx @modelcontextprotocol/inspector --cli uv run server.py --method tools/list
De eerste keer wordt om toestemming gevraagd om het pakket te downloaden. Daarna zie je JSON met count_words en days_between, elk met het invoerschema dat de SDK uit je type hints heeft gemaakt.
Roep nu een tool aan:
npx @modelcontextprotocol/inspector --cli uv run server.py \
--method tools/call --tool-name days_between \
--tool-args-json '{"start":"2026-11-15","end":"2027-01-01"}'
Verwachte uitvoer:
{
"content": [
{
"type": "text",
"text": "47"
}
],
"structuredContent": {
"result": 47
},
"isError": false
}
De SDK kan ook de webinterface van de Inspector starten:
uv run mcp dev server.py
Die toont een lokaal adres zoals http://127.0.0.1:6274?MCP_INSPECTOR_API_TOKEN=... en opent het in je browser. Zet op het scherm Servers de verbindingsschakelaar naast je server aan, open Tools, kies count_words, typ wat tekst en klik op Execute Tool (tool uitvoeren). Druk op Ctrl+C in de terminal als je klaar bent.
Stap 5: koppel hem aan een AI-app
Verbinden met een host betekent dat je de host vertelt met welk commando je server start. Voor dit project is dat commando:
uv --directory /ABSOLUTE/PATH/TO/handy-tools run server.py
Voer pwd uit in de projectmap om het echte pad te krijgen. Probeer het commando eerst zelf. Er verschijnt niets en het commando blijft lopen, en dat klopt: de server wacht tot een host iets zegt. Druk op Ctrl+C om hem te stoppen.
Veel apps accepteren hetzelfde JSON-blok voor dat commando:
{
"mcpServers": {
"handy-tools": {
"command": "uv",
"args": ["--directory", "/ABSOLUTE/PATH/TO/handy-tools", "run", "server.py"]
}
}
}
Waar het moet staan, hangt af van de app:
- Cursor: sla het op als
.cursor/mcp.jsonin een project, of als~/.cursor/mcp.jsonom het overal te gebruiken, volgens de MCP-documentatie van Cursor. Die documentatie noemt ook een veld"type": "stdio"voor lokale servers, al laten de eigen voorbeelden het weg. - VS Code: voer MCP: Add Server uit vanuit het Command Palette, kies Command (stdio) en vul het startcommando in, volgens de documentatie van VS Code.
- Claude Desktop: voer
uv run mcp install server.pyuit; dat schrijft de configuratie voor je. Het is de enige host die de SDK automatisch configureert.
Start de app opnieuw en vraag dan bijvoorbeeld:
Use the days_between tool: how many days from 2026-11-15 to 2027-01-01?
Het antwoord zou 47 moeten zijn. Houd er rekening mee dat tools op je eigen computer draaien met de rechten van je account, dus stel alleen acties beschikbaar die je een model met een gerust hart laat uitvoeren. Een voorbeeld van een grotere kant-en-klare server vind je in onze gids over Chrome DevTools MCP.

Veelvoorkomende fouten en oplossingen
ModuleNotFoundError: No module named 'mcp.server.fastmcp': de code is geschreven voor SDK 1.x. In 2.x heet de klasseMCPServeren importeer je hem metfrom mcp.server import MCPServer. Pas de import aan, of zet de versie vast opmcp<2om oude code te blijven draaien.TypeError: The @tool decorator was used incorrectly: je hebt@mcp.toolzonder haakjes geschreven. Gebruik@mcp.tool().- De app toont je server niet: meestal komt dat door een relatief pad. Gebruik het absolute pad naar het project, en als de app
uvniet kan vinden, vervanguvdan door het volledige pad uitwhich uv(macOS en Linux) ofwhere uv(Windows). Sluit de app helemaal af en open hem opnieuw nadat je de configuratie hebt aangepast. - De verbinding valt weg of de lijst met tools is leeg: via stdio draagt stdout het protocol zelf. Eén verdwaalde
print()kan dat verstoren. Gebruik de moduleloggingvan Python, die naar stderr schrijft. npm warn deprecated @modelcontextprotocol/inspector@0.15.0: v1 is deprecated, of een toolaanroep mislukt metField required: je Node.js is te oud voor Inspector 2.x. In een test op Node 20 installeerdenpxstilletjes de oude release 0.15.0, die--tool-args-jsonnegeert. Controleernode --versionen upgrade naar een ondersteunde release.npx not foundbij het uitvoeren vanmcp dev: de Inspector is een Node.js-app. Installeer eerst Node.js.Error executing tool <name>zonder bericht: de tool is gecrasht door een exceptie waar je niet op had gerekend. De traceback staat in het log van de server, niet in het resultaat.
Wist je dat?
Via stdio draagt stdout het protocol zelf, dus één verdwaalde print() in je server kan de verbinding verstoren. De logging-module van Python schrijft in plaats daarvan naar stderr.
Tot slot
Een werkende MCP-server is een Python-bestand met een paar gedecoreerde functies. Schrijf de tool, controleer hem in het geheugen met Client(mcp), bevestig via stdio met de Inspector dat hij werkt en geef daarna elke host het startcommando. Vanaf hier kun je resources en prompts toevoegen, of dezelfde code via HTTP aanbieden met mcp.run(transport="streamable-http"). Heeft je agent eerder geschreven instructies nodig dan nieuwe functies? Dan behandelt onze gids over agent skills in Claude Code die kant.
Veelgestelde vragen
Wat is het verschil tussen een MCP-host, -client en -server?
De host is de AI-app waarmee je praat, zoals een chatassistent of code-editor. De client zit in de host en spreekt MCP. De server is wat jij bouwt, en die kan tools, resources en prompts aanbieden.
Waarom krijg ik No module named mcp.server.fastmcp?
Die code is geschreven voor SDK 1.x. In 2.x heet de klasse MCPServer en importeer je hem met from mcp.server import MCPServer. Pas de import aan, of zet de versie vast op mcp<2 om oude code te blijven draaien.
Kan ik een MCP-server testen zonder AI-app?
Ja. De Client-klasse van de SDK maakt in het geheugen verbinding met je serverobject, zonder subproces, poort of AI. De CLI-modus van MCP Inspector start de server daarna via stdio, zoals een echte host dat zou doen.
Welke Node.js-versie heeft MCP Inspector nodig?
Inspector 2.15.0 vereist Node ^22.23.4, ^24.22.1 of >=26.12.1. Op oudere Node-versies kan npx stilletjes de oude release 0.15.0 installeren, die –tool-args-json negeert.
Korte quiz
Welke klasse maakt in SDK 2.x een MCP-server aan?
- FastMCP
- ToolError
- MCPServer
SDK 2.x heeft de belangrijkste serverklasse hernoemd naar MCPServer, die je importeert uit mcp.server.
Wat kan een verdwaalde print() doen met een MCP-server via stdio?
- De protocolstroom verstoren
- Niets, uitvoer wordt genegeerd
- De server herstarten
Via stdio draagt stdout het protocol zelf, dus extra uitvoer kan het verstoren.
Waar haalt de SDK het invoerschema van een tool vandaan?
- Uit een JSON-bestand dat je zelf schrijft
- Uit de type hints van de functie
- Uit het configuratiebestand van de host
De SDK leest het invoerschema uit de type hints, dus je schrijft geen JSON.
Bronnen
Links voor het laatst gecontroleerd op 15 november 2026.
- Build an MCP server (official tutorial)
- What is the Model Context Protocol?
- MCP Python SDK README, v2.3.0
- Python SDK: First steps
- Python SDK: Connect to a real host
- Python SDK: Testing
- Python SDK: Running your server
- Python SDK: Handling errors
- Python SDK: Troubleshooting
- mcp on PyPI
- MCP Inspector README, 2.15.0
- Inspector: smoke-testing an MCP server from the shell
- Installing uv
- uv: creating projects
- Cursor: Model Context Protocol
- VS Code: add and manage MCP servers





Schrijf een reactie