Πώς να φτιάξετε έναν MCP Server: Οδηγός βήμα προς βήμα σε Python και TypeScript (2026)

Μπορείτε να φτιάξετε έναν MCP server που καλεί πραγματικά το Claude σε περίπου 15 λεπτά. Το μετρήσαμε σε Node 20 και Python 3.11: ένα λειτουργικό εργαλείο add, που εκτελείται μέσω stdio και ανιχνεύεται από το Claude Desktop, πήρε 14 λεπτά την πρώτη φορά και λιγότερο από 5 μόλις κατανοήσετε τη δομή του. Αυτός ο οδηγός χτίζει τον ίδιο server δύο φορές, μία φορά σε Python με το FastMCP 2.x και μία φορά σε TypeScript με το @modelcontextprotocol/sdk 1.x — ώστε να μπορείτε να επιλέξετε το stack σας και να αντιγράψετε πραγματικό κώδικα. Αν θέλετε πρώτα την αρχιτεκτονική και τη θεωρία του πρωτοκόλλου, ο οδηγός εννοιών Model Context Protocol τα έχει όλα· εδώ απλώς χτίζουμε.

Γρήγορη Εκκίνηση MCP Server: Τι Φτιάχνετε

Ένας MCP server είναι ένα μικρό πρόγραμμα που εκθέτει εργαλεία, δεδομένα και πρότυπα prompts σε AI clients όπως το Claude, το Cursor ή το VS Code μέσω του Model Context Protocol. Γράφετε τον server μία φορά και οποιοσδήποτε client συμβατός με MCP μπορεί να τον καλέσει. Σε αυτόν τον οδηγό θα φτιάξετε έναν server με δύο εργαλεία (μια αριθμομηχανή add και έναν βοηθό fetch_url), θα τον εκτελέσετε τοπικά μέσω stdio, θα τον δοκιμάσετε και θα τον συνδέσετε με έναν πραγματικό client.

Εδώ είναι όλα όσα χρειάζεστε πριν ξεκινήσετε.

Και οι δύο διαδρομές παράγουν έναν server που συμπεριφέρεται πανομοιότυπα. Επιλέξτε τη γλώσσα στην οποία η ομάδα σας ήδη αναπτύσσει. Αν δεν έχετε προτίμηση, ξεκινήστε με Python, καθώς το FastMCP κάνει τον πρώτο server πιο σύντομο.

Τι Εκθέτει Πραγματικά ένας MCP Server;

Πριν γράψετε κώδικα, βοηθάει να γνωρίζετε τα τρία πράγματα που μπορεί να προσφέρει ένας server. Ένας MCP server εκθέτει εργαλεία (συναρτήσεις που μπορεί να καλέσει το μοντέλο, όπως "αναζήτηση στη βάση δεδομένων"), πόρους (δεδομένα μόνο για ανάγνωση που μπορεί να φορτώσει το μοντέλο, όπως ένα αρχείο ή μια εγγραφή) και prompts (επαναχρησιμοποιήσιμα πρότυπα prompts). Οι περισσότεροι servers που θα φτιάξετε θα επικεντρώνονται στα εργαλεία· οι πόροι και τα prompts είναι προαιρετικά.

Ορισμός MCP server: μια διεργασία που μιλάει το Model Context Protocol και διαφημίζει μια λίστα εργαλείων, πόρων και prompts που ένας AI client μπορεί να ανακαλύψει και να επικαλεστεί κατά τον χρόνο εκτέλεσης.

Ο client (για παράδειγμα, το Claude Desktop) λειτουργεί ως host. Εκκινεί ή συνδέεται με τον server σας, ρωτάει "τι εργαλεία έχεις;" και μετά τα καλεί όταν το μοντέλο αποφασίσει ότι ένα εργαλείο είναι χρήσιμο. Ποτέ δεν καλείτε το μοντέλο από μέσα στον server. Η ροή λειτουργεί αντίστροφα.

Αυτή η κατεύθυνση έχει σημασία. Ο server σας είναι ένας παθητικός πάροχος. Περιμένει να συνδεθεί ο client, απαντά στο αίτημα ανακάλυψης και εκτελεί όποιο εργαλείο κληθεί. Κρατήστε αυτό το νοητικό μοντέλο και το υπόλοιπο του οδηγού θα μπει στη θέση του.

Πώς να φτιάξετε έναν MCP Server σε Python (Βήμα προς Βήμα)

Η Python είναι η γρηγορότερη διαδρομή για έναν λειτουργικό server επειδή το FastMCP διαχειρίζεται τις λεπτομέρειες του πρωτοκόλλου και μετατρέπει απλές συναρτήσεις σε εργαλεία με έναν decorator. Όλα τα παρακάτω χρησιμοποιούν το επίσημο Python SDK. Ακολουθούν τα τέσσερα βήματα.

Βήμα 1: Ρύθμιση του project. Χρησιμοποιήστε το uv, which is now the standard for MCP Python projects:

uv init mcp-demo
cd mcp-demo
uv add "mcp[cli]"

Αν προτιμάτε το pip: python -m venv .venv && source .venv/bin/activate && pip install "mcp[cli]".

Βήμα 2: Συγγραφή του server. Δημιουργήστε το server.py:

from mcp.server.fastmcp import FastMCP
import httpx

# Name shows up in the client's tool list
mcp = FastMCP("demo-server")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers and return the sum."""
    return a + b

@mcp.tool()
async def fetch_url(url: str) -> str:
    """Fetch a URL and return the first 2000 characters of the body."""
    async with httpx.AsyncClient(timeout=10) as client:
        resp = await client.get(url)
        return resp.text[:2000]

if __name__ == "__main__":
    mcp.run()  # defaults to stdio transport

Δύο πράγματα να προσέξετε. Το docstring γίνεται η περιγραφή του εργαλείου που διαβάζει το μοντέλο, οπότε γράψτε το σαν οδηγία. Και οι υποδείξεις τύπων (a: int) γίνονται αυτόματα το σχήμα εισόδου, οπότε το FastMCP παράγει το JSON Schema για εσάς.

Βήμα 3: Εκτέλεσή του. Το mcp.run() ξεκινά τον server σε stdio, τη μεταφορά δεδομένων που εκκινούν οι clients τοπικά. Δεν το εκτελείτε άμεσα κατά την ανάπτυξη· ο client το εκκινεί. Για έναν γρήγορο έλεγχο λειτουργίας, χρησιμοποιήστε τον dev runner:

uv run mcp dev server.py

Βήμα 4: Επιστροφή καθαρής εξόδου. Μια παγίδα που αξίζει να επισημανθεί τώρα: επιστρέψτε ένα string ή μια τιμή με τύπο, όχι ένα γυμνό nested dict που ελπίζετε να αποδοθεί σωστά. Θα επανέλθουμε στο γιατί στην ενότητα παραγωγής, αλλά συνοπτικά, οι ασαφείς τύποι επιστροφής μπορούν να περικοπούν σιωπηρά σε ορισμένους clients.

Αυτός είναι ένας πλήρης MCP server σε Python. Δύο εργαλεία, πραγματικές κλήσεις δικτύου, αυτόματο σχήμα. Στη συνέχεια, το ίδιο πράγμα σε TypeScript.

Πώς να φτιάξετε έναν MCP Server σε TypeScript (Βήμα προς Βήμα)

Η διαδρομή TypeScript χρησιμοποιεί απευθείας το επίσημο TypeScript SDK και το zod για την επικύρωση εισόδου. Είναι λίγο πιο verbose από το FastMCP, αλλά οι τύποι είναι εξαιρετικοί και αναπτύσσεται καθαρά σε hosts Node.

Βήμα 1: Ρύθμιση του project.

mkdir mcp-demo && cd mcp-demo
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node tsx

Βήμα 2: Συγγραφή του server. Δημιουργήστε το server.ts:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "demo-server", version: "1.0.0" });

server.tool(
  "add",
  "Add two numbers and return the sum.",
  { a: z.number(), b: z.number() },
  async ({ a, b }) => ({
    content: [{ type: "text", text: String(a + b) }],
  }),
);

server.tool(
  "fetch_url",
  "Fetch a URL and return the first 2000 characters.",
  { url: z.string().url() },
  async ({ url }) => {
    const resp = await fetch(url);
    const body = await resp.text();
    return { content: [{ type: "text", text: body.slice(0, 2000) }] };
  },
);

const transport = new StdioServerTransport();
await server.connect(transport);

Βήμα 3: Εκτέλεσή του. Κατά την ανάπτυξη: npx tsx server.ts. Για παραγωγή, κάντε compile με tsc και εκτελέστε το built .js με Node. Προσέξτε τη μορφή επιστροφής: κάθε εργαλείο επιστρέφει { content: [{ type: "text", text: ... }] }. Αυτός ο ρητός πίνακας content είναι το ισοδύναμο TypeScript του κανόνα "επιστροφή καθαρής συμβολοσειράς" από την Python. Το SDK θέλει typed content blocks, όχι raw objects.

Βήμα 4: Επικύρωση εισόδων με zod. Το σχήμα z.string().url() απορρίπτει κακή είσοδο πριν εκτελεστεί ο handler σας, κάτι που ακριβώς θέλετε όταν ένα μοντέλο δημιουργεί τα arguments.

Ίδια δύο εργαλεία, ίδια συμπεριφορά, ιδιωματικό TypeScript. Τώρα ας αποφασίσουμε πώς πρέπει οι clients να προσεγγίζουν τον server σας.

stdio vs Streamable HTTP: Ποια Μεταφορά Δεδομένων Να Χρησιμοποιήσετε;

Οι MCP servers επικοινωνούν μέσω μιας από δύο μεταφορές δεδομένων. Το stdio εκτελεί τον server ως μια τοπική subprocess που εκκινεί ο client και επικοινωνεί μέσω της τυπικής εισόδου/εξόδου. Το Streamable HTTP εκτελεί τον server ως μια δικτυακή υπηρεσία στην οποία συνδέονται οι clients μέσω HTTP. Επιλέξτε βάσει του πού πρέπει να βρίσκεται ο server.

Ο κανόνας: χτίστε και δοκιμάστε σε stdio, μετά μεταβείτε σε Streamable HTTP μόνο όταν περισσότερα από ένα άτομα ή μηχανήματα χρειάζονται τον server. Οι περισσότεροι servers δεν χρειάζεται ποτέ να φύγουν από το stdio. Οι κλήσεις mcp.run() και StdioServerTransport() παραπάνω είναι ήδη stdio, οπότε είστε έτοιμοι για ανάπτυξη.

Πώς να Δοκιμάσετε τον MCP Server σας με το Inspector

Πριν συνδέσετε τον server σας στο Claude, δοκιμάστε τον απομονωμένα με το MCP Inspector. Είναι ένα browser UI που συνδέεται στον server σας,列出 τα εργαλεία του και σας επιτρέπει να τα καλέσετε χειροκίνητα. Εκτελέστε το against τον server σας:

# Python
npx @modelcontextprotocol/inspector uv run server.py
# TypeScript
npx @modelcontextprotocol/inspector npx tsx server.ts

Το Inspector ανοίγει μια τοπική σελίδα όπου μπορείτε να δείτε τα εργαλεία add και fetch_url, να κάνετε μια δοκιμαστική κλήση και να διαβάσετε την raw απόκριση. Αυτή είναι η καλύτερη συνήθεια για την ανάπτυξη MCP. Αν το σχήμα ενός εργαλείου είναι κακοδιατυπωμένο ή μια τιμή επιστροφής είναι λάθος, θα το δείτε εδώ σε δευτερόλεπτα αντί να κοιτάζετε μια σιωπηλή αποτυχία μέσα στο Claude. Εντοπίσαμε έτσι ένα κακό σχήμα εισόδου που διαφορετικά θα κόστιζε έναν πλήρη κύκλο debugging μέσω του client. Δοκιμάστε στο Inspector πρώτα, κάθε φορά.

Πώς να Συνδέσετε τον MCP Server σας σε Claude Desktop, Claude Code και Cursor

Όταν το Inspector είναι ικανοποιημένο, δείξτε έναν πραγματικό client στον server σας. Κάθε client διαβάζει ένα αρχείο config που του λέει πώς να εκκινήσει τον server σας μέσω stdio.

Claude Desktop. Επεξεργαστείτε το claude_desktop_config.json (σε macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "demo-server": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/mcp-demo", "run", "server.py"]
    }
  }
}

Επανεκκινήστε το Claude Desktop και τα εργαλεία σας εμφανίζονται κάτω από το εικονίδιο connectors.

Claude Code. Προσθέστε τον server με μία εντολή από το project σας: claude mcp add demo-server -- uv run server.py. Το Claude Code το αποθηκεύει στο config του project σας και το φορτώνει κατά την εκκίνηση. Αν χρησιμοποιείτε επίσης hooks για scripting στο Claude Code, ο οδηγός hooks του Claude Code ταιριάζει καλά με custom MCP εργαλεία.

Cursor. Προσθέστε το ίδιο block mcpServers στο .cursor/mcp.json στη ρίζα του project σας. Η δομή ταιριάζει με αυτή του Claude Desktop. Για ένα πραγματικό παράδειγμα ενός MCP server που εκτελείται μέσα στο Claude Code, δείτε πώς συνδέσαμε το Higgsfield στο Claude Code.

Χρησιμοποιήστε absolute paths σε κάθε config. Τα relative paths είναι ο πιο συνηθισμένος λόγος αποτυχίας εκκίνησης ενός server.

Ανάπτυξη MCP Server σε Παραγωγή (Auth και Hosting)

Όταν ο server σας χρειάζεται να κοινοποιηθεί, μετακινήστε τον από stdio σε Streamable HTTP και προσθέστε τρία πράγματα: authentication, error handling και host.

• Authentication. Οι απομακρυσμένοι MCP servers πρέπει να χρησιμοποιούν OAuth 2.1 σύμφωνα με τις προδιαγραφές authorization του MCP. Για εσωτερικά εργαλεία, ένας έλεγχος bearer-token στο HTTP endpoint είναι το πρακτικό ελάχιστο. Ποτέ μην δημοσιεύετε έναν δημόσιο, μη authenticated tool server, επειδή ένα εργαλείο που εκτελεί SQL ή χτυπά internal APIs είναι μια ζωντανή επιφάνεια επίθεσης.
• Error handling. Τυλίξτε τα bodies των εργαλείων σε try/except (ή try/catch) και επιστρέψτε ένα typed μήνυμα σφάλματος αντί να πετάξετε exception. Το μοντέλο διαχειρίζεται πολύ καλύτερα το "το query απέτυχε, ecco γιατί" από μια διακοπή σύνδεσης.
• Hosting. Οποιαδήποτε πλατφόρμα που εκτελεί μια μακρόβια διεργασία Node ή Python λειτουργεί: ένα μικρό VPS, Fly.io, Railway ή ένα container στις δικές σας υποδομές. Διατηρήστε τη διεργασία warm, καθώς τα cold starts προσθέτουν καθυστέρηση στην πρώτη κλήση εργαλείου.
• Concurrency και κόστος. Αν τα εργαλεία σας καλούν ένα LLM ή paid API downstream, βάλτε ένα gateway μπροστά τους. Η συλλογή μας για εργαλεία LLM gateway καλύπτει τον rate limiting και το fallback, και τα εργαλεία context engineering βοηθούν να μην φουσκώνουν οι έξοδοι των εργαλείων το context window του μοντέλου.

Για Python, αλλάξτε την κλήση run σε mcp.run(transport="streamable-http")· για TypeScript, αντικαταστήστε το StdioServerTransport με το StreamableHTTPServerTransport του SDK. Οι ορισμοί των εργαλείων δεν αλλάζουν καθόλου — αυτός είναι ο σκοπός της abstraction της μεταφοράς δεδομένων.

Τι Μάθαμε Αναπτύσσοντας MCP Servers σε Παραγωγή

Έχουμε φτιάξει MCP servers για εσωτερική χρήση στο Techsy, και μερικά μαθήματα εμφανίζονται μόνο όταν πέσει πραγματική κίνηση. Εδώ είναι τι μετρήσαμε και πού δυσκολευτήκαμε.

Ο πρώτος server που αναπτύξαμε ήταν ένα εργαλείο query Postgres μόνο για ανάγνωση, χτισμένο με FastMCP 2.x στο Python mcp 1.x SDK, αργότερα ξαναγραμμένο σε @modelcontextprotocol/sdk 1.x για σύγκριση. Σε ένα stack 2026 (Node 20, Python 3.11), οι τοπικές κλήσεις εργαλείων stdio πρόσθεσαν περίπου 8 έως 12 ms overhead μεταφοράς ανά κλήση. Μόλις μετακινήσαμε τον ίδιο server σε Streamable HTTP σε ένα VPS, το κόστος ανά κλήση ανέβηκε σε 40 έως 70 ms, σχεδόν αποκλειστικά λόγω network round-trip και όχι κόστους πρωτοκόλλου. Το cold-start του FastMCP ήταν περίπου 300 ms για τη διεργασία, γι' αυτό κρατάμε τη διεργασία παραγωγής warm.

Η παγίδα που μας κόστισε περίπου δύο ώρες: ένα εργαλείο που επέστρεφε ένα raw Python dict αποδιδόταν καλά στο Inspector αλλά ερχόταν περικομμένο μέσα στο Claude Desktop. Η τυλίξηση της τιμής επιστροφής ως typed text string το έλυσε instantaneously. Γι' αυτό αυτός ο οδηγός επιστρέφει strings και content text blocks παντού αντί για nested objects. Η άλλη συνήθεια που απέδωσε αμέσως ήταν η εκτέλεση κάθε server μέσω npx @modelcontextprotocol/inspector πριν αγγίξουμε ένα config client, which surfaced a malformed input schema on the TypeScript rewrite that would otherwise have failed silently in Cursor.

Αν επιλέγετε ποια εργαλεία να χτίσετε σε servers εξαρχής, η λίστα μας με τους καλύτερους MCP servers του 2026 είναι μια good idea bank.

Πώς Προσεγγίζει το Techsy την Ανάπτυξη MCP

Στο Techsy χτίζουμε MCP servers ως μέρος των συστημάτων AI agent που αναπτύσσουμε για clients, συνδέοντας agents με εσωτερικές βάσεις δεδομένων, CRMs και APIs μέσω ενός typed layer εργαλείων. Η προσέγγισή μας είναι να ξεκινάμε στενά (ένα καλά δοκιμασμένο εργαλείο μέσω stdio), να το επικυρώνουμε στο Inspector και μετά να το προάγουμε σε authenticated HTTP service μόνο όταν περισσότεροι από ένας agent το χρειάζονται. Συνδυάζουμε custom servers με το Claude Agent SDK όταν η λογική του agent γίνεται complex.

Αυτή είναι η honest version: οι περισσότερες ομάδες over-build τον πρώτο server τους. Σπάνια χρειάζεστε HTTP, OAuth και δώδεκα εργαλεία την πρώτη μέρα. Αν θέλετε ένα δεύτερο ζευγάρι μάτια σε μια ενσωμάτωση MCP, λάβετε μια δωρεάν consultation και θα σας πούμε αν είναι μια δουλειά ενός εργαλείου stdio ή κάτι που πραγματικά χρειάζεται infrastructure.

Συχνές Ερωτήσεις

Να φτιάξω τον MCP server μου σε Python ή TypeScript;

Χρησιμοποιήστε ό,τι ήδη αναπτύσσει η ομάδα σας. Η Python με το FastMCP είναι η συντομότερη διαδρομή για έναν πρώτο λειτουργικό server επειδή ένας decorator μετατρέπει μια συνάρτηση σε εργαλείο. Το TypeScript με το επίσημο SDK είναι ελαφρώς πιο verbose αλλά σας δίνει εξαιρετικούς τύπους και αναπτύσσεται καθαρά σε hosts Node. Και τα δύο παράγουν servers που συμπεριφέρονται πανομοιότυπα στον client.

Χρειάζομαι ένα framework όπως το FastMCP για να φτιάξω έναν MCP server;

Όχι, αλλά βοηθάει. Το FastMCP περιλαμβάνεται στο επίσημο Python mcp SDK και αφαιρεί το μεγαλύτερο μέρος του boilerplate του πρωτοκόλλου. Μπορείτε να χρησιμοποιήσετε το lower-level Server API για fine-grained control, αλλά για σχεδόν κάθε server το FastMCP (Python) ή το McpServer (TypeScript) είναι το σωστό εργαλείο και απαιτεί πολύ λιγότερο κώδικα.

Πώς κάνω debug έναν MCP server που δεν λειτουργεί;

Εκτελέστε τον πρώτα μέσω του MCP Inspector: npx @modelcontextprotocol/inspector ακολουθούμενο από την εντολή run σας. Το Inspector列出 τα εργαλεία σας και σας επιτρέπει να τα καλέσετε απευθείας, ώστε να επιβεβαιώσετε ότι ο server λειτουργεί πριν κατηγορήσετε τον client. Αν το Inspector είναι εντάξει αλλά ο client όχι, ελέγξτε ότι το config σας χρησιμοποιεί absolute paths και ότι επανεκκινήσατε τον client.

Είναι το FastMCP επίσημο μέρος του MCP;

Ναι. Το FastMCP περιλαμβάνεται στο επίσημο Model Context Protocol Python SDK ως το high-level server interface. Ο decorator @mcp.tool() που χρησιμοποιείτε είναι ο recommended τρόπος για να φτιάξετε servers σε Python, όχι ένα third-party add-on.

Ποια είναι η διαφορά μεταξύ local και remote MCP server;

Ένας local server εκτελείται στο μηχάνημά σας μέσω stdio, εκκινείται από τον client ως subprocess και είναι καλύτερος για προσωπικά εργαλεία και development. Ένας remote server εκτελείται ως web service μέσω Streamable HTTP και είναι προσβάσιμος από πολλούς clients, which requires OAuth 2.1 authentication. Χτίστε πρώτα local, going remote only when sharing.

Σε ποιες γλώσσες μπορώ να φτιάξω έναν MCP server;

Το Model Context Protocol έχει επίσημα SDKs για Python, TypeScript, Java, Kotlin και C#, με community SDKs σε άλλες γλώσσες. Επειδή το MCP είναι ένα wire protocol, οποιαδήποτε γλώσσα που μπορεί να διαβάσει και να γράψει JSON-RPC μέσω stdio ή HTTP μπορεί να implement一个 server, αλλά τα επίσημα SDKs σας γλιτώνουν αυτή τη δουλειά.

Λειτουργεί ένας MCP server με ChatGPT και Gemini, ή μόνο με Claude;

Το MCP είναι ένα open standard που υιοθετείται σε όλο το ecosystem του agentic AI, including ChatGPT, Gemini, Cursor και VS Code Copilot. Ένας single server που φτιάχνετε λειτουργεί με οποιονδήποτε συμβατό client. Δεν γράφετε ξεχωριστή integration per model, which is the whole point of the protocol.

Πόσο χρόνο παίρνει να φτιάξετε έναν λειτουργικό MCP server;

Ένας πρώτος server με ένα ή δύο εργαλεία που εκτελείται μέσω stdio παίρνει περίπου 15 λεπτά μόλις εγκατασταθεί το runtime σας. Μετρήσαμε 14 λεπτά για έναν πρωτάρη σε Node 20 και κάτω από 5 λεπτά για μια επαναλαμβανόμενη build. Η προσθήκη authentication, HTTP transport και production hosting είναι αυτό που παίρνει πραγματικό χρόνο, not the server itself.

Σχετικά με τον Συγγραφέα

Ο Mert Batur Gurbuz είναι Συνιδρυτής του Techsy.io, where the team ships AI agents, automation systems, and voice/SDR pipelines for B2B clients. Σπουδάζει στο Πανεπιστήμιο του Birmingham και γράφει για το LLM tooling stack που χρησιμοποιεί πραγματικά η ομάδα Techsy σε παραγωγή. Συνδεθείτε στο LinkedIn.

Mert Batur Gurbuz, Συνιδρυτής, Techsy.io, Πανεπιστήμιο του Birmingham