Πλήρης Διαμόρφωση Διακομιστή MCP
Σε αυτήν τη σελίδα
Συγκεντρώνοντας τα Πάντα
Έχετε εξετάσει κάθε παράμετρο μεμονωμένα. Αυτό το μάθημα τις συνδυάζει σε πλήρεις διαμορφώσεις, ακριβώς όπως θα τις γράψετε στην πράξη, παρουσιάζοντας κάθε φορά τον αντίστοιχο κώδικα και στα δύο κύρια SDK. Ο στόχος δεν είναι η εισαγωγή νέων εννοιών, αλλά η παροχή προτύπων που μπορείτε να προσαρμόσετε άμεσα.
Ακολουθεί μια επισκόπηση των έξι παραμέτρων, μαζί με την υποχρεωτική ή προαιρετική τους φύση.
| Παράμετρος | Υποχρεωτική | Ρόλος |
|---|---|---|
server_url | Ναι | HTTPS URL του διακομιστή MCP |
server_label | Ναι | Πρόθεμα κλήσης εργαλείου |
server_description | Όχι | Καθοδηγεί το Grok στην επιλογή διακομιστή |
allowed_tool_names | Όχι | Περιορίζει τα προσβάσιμα εργαλεία |
authorization | Όχι | Διακριτικό πιστοποίησης |
headers | Όχι | Πρόσθετες κεφαλίδες HTTP |
Η Πιο Απλή Περίπτωση
Δύο παράμετροι αρκούν όταν ο διακομιστής είναι δημόσιος και δεν απαιτεί πιστοποίηση.
# xAI SDK
tools = [mcp(server_url="https://mcp.deepwiki.com/mcp", server_label="deepwiki")]
# Responses API (OpenAI)
tools = [{
"type": "mcp",
"server_url": "https://mcp.deepwiki.com/mcp",
"server_label": "deepwiki"
}]
Αυτό είναι ακριβώς ό,τι θα γράψετε για το DeepWiki. Το Grok έχει τότε πρόσβαση σε όλα τα εργαλεία του διακομιστή, κάτι που παραμένει αποδεκτό εδώ καθώς πρόκειται για μια δημόσια υπηρεσία ανάγνωσης μόνο. Μόλις ο διακομιστής ανήκει στον οργανισμό σας, αυτή η διαμόρφωση καθίσταται ανεπαρκής.
Ένας Εσωτερικός Διακομιστής Ανάγνωσης Μόνο
Ας κάνουμε ένα βήμα παραπάνω: ένα εταιρικό CRM που ο πράκτορας πρέπει να μπορεί να ερωτά αλλά ποτέ να τροποποιεί. Προστίθενται τρεις παράμετροι, καθεμία για έναν ξεχωριστό λόγο—η περιγραφή καθοδηγεί το μοντέλο, το διακριτικό αποδεικνύει την ταυτότητα και η λίστα επιτρεπόμενων απαγορεύει τις εγγραφές.
# xAI SDK
tools = [
mcp(
server_url="https://api.monentreprise.com/mcp",
server_label="crm",
server_description="Internal CRM. Contact and company lookup only.",
authorization=f"Bearer {os.getenv('CRM_TOKEN')}",
allowed_tool_names=["search_contacts", "get_contact", "list_companies"]
)
]
# Responses API (OpenAI)
tools = [{
"type": "mcp",
"server_url": "https://api.monentreprise.com/mcp",
"server_label": "crm",
"server_description": "Internal CRM. Contact and company lookup only.",
"authorization": f"Bearer {os.getenv('CRM_TOKEN')}",
"allowed_tool_names": ["search_contacts", "get_contact", "list_companies"]
}]
Συγκρίνετε τα δύο μπλοκ: το περιεχόμενο είναι ίδιο· αλλάζει μόνο ο περιβάλλων κώδικας. Η βοηθητική συνάρτηση mcp() δέχεται ονομαστικά ορίσματα· η μορφή της OpenAI αναμένει ένα λεξικό με ένα επιπλέον κλειδί "type". Αυτή είναι η μόνη διαφορά που πρέπει να θυμάστε όταν μεταφέρετε μια διαμόρφωση από το ένα SDK στο άλλο.
Μια Περιεκτική Διαμόρφωση
Τελευταίο βήμα, με όλες τις έξι παραμέτρους συνδυασμένες σε μια κλήση πραγματικού σεναρίου στο xAI SDK.
import os
from xai_sdk import Client
from xai_sdk.tools import mcp
client = Client(api_key=os.getenv("XAI_API_KEY"))
chat = client.chat.create(
model="grok-4.20-0309-reasoning",
tools=[
mcp(
server_url="https://tools.monentreprise.com/v1/mcp",
server_label="outils-internes",
server_description="Internal tools platform: document management, support tickets, knowledge base. Read-only access.",
authorization=f"Bearer {os.getenv('TOOLS_MCP_TOKEN')}",
headers={
"X-Organization-Id": os.getenv("ORG_ID"),
"X-Environment": "production",
"X-Request-Source": "grok-agent"
},
allowed_tool_names=[
"search_documents",
"get_document",
"search_tickets",
"get_ticket",
"search_knowledge_base"
]
)
],
include=["verbose_streaming"],
)
Παρατηρήστε την εσωτερική συνοχή αυτού του παραδείγματος. Η περιγραφή ανακοινώνει πρόσβαση ανάγνωσης μόνο και τα πέντε επιτρεπόμενα εργαλεία είναι όλα λειτουργίες ερωτήματος—καμία αντίφαση μεταξύ αυτού που πιστεύει το μοντέλο ότι μπορεί να κάνει και αυτού που επιτρέπει η διαμόρφωση. Η κεφαλίδα X-Environment ορισμένη σε production εμποδίζει έναν πράκτορα δοκιμής να γράψει σε ζωντανά δεδομένα, ενώ το X-Request-Source θα κάνει τα ίχνη του διακομιστή σας εκμεταλλεύσιμα εάν χρειαστεί να εντοπίσετε την προέλευση ενός απροσδόκητου αιτήματος.
Έλεγχος Πριν την Ανάπτυξη
Έξι σημεία αξίζουν αναθεώρηση πριν από οποιαδήποτε ανάπτυξη σε παραγωγή και το καθένα αντιστοιχεί σε μια παγίδα που συναντήσατε νωρίτερα σε αυτό το μάθημα. Το URL πρέπει να είναι HTTPS με έγκυρο πιστοποιητικό, διαφορετικά τίποτα δεν θα περάσει. Η ετικέτα πρέπει να παραμείνει σύντομη, περιγραφική και μοναδική μέσα στη διαμόρφωση. Η περιγραφή πρέπει να ταιριάζει με τα εργαλεία που εκτίθενται πραγματικά, διαφορετικά το μοντέλο θα επιχειρήσει κλήσεις destined να αποτύχουν. Τα επιτρεπόμενα εργαλεία πρέπει να μειωθούν στο αυστηρό ελάχιστο. Το διακριτικό πρέπει να προέρχεται από μεταβλητή περιβάλλοντος, όχι από τον πηγαίο κώδικα. Και οι πρόσθετες κεφαλίδες πρέπει να είναι ακριβώς αυτές που αναμένει ο διακομιστής σας, με τη σωστή χρήση πεζών/κεφαλαίων—ένα σφάλμα πεζών/κεφαλαίων στο X-Organization-Id προκαλεί μια σιωπηρή αποτυχία που είναι ιδιαίτερα οδυνηρή στη διάγνωση.
Βασικά σημεία
- Η ελάχιστη διαμόρφωση απαιτεί μόνο τις
server_urlκαιserver_label - Προσθέστε την
server_descriptionγια να καθοδηγήσετε το Grok, ειδικά σε ρυθμίσεις πολλαπλών διακομιστών - Περιορίστε με την
allowed_tool_namesγια ασφάλεια και απόδοση - Χρησιμοποιήστε τις
authorizationκαιheadersγια πιστοποίηση - Και τα δύο SDK (native xAI και OpenAI Responses) δέχονται τις ίδιες παραμέτρους με διαφορετική σύνταξη