Wie Claude Code MCP-Server findet: Konfiguration, Scopes und Vorrangregeln erklärt
Claude Code verbindet sich erst mit einem MCP-Server, wenn dieser in der Konfiguration eingetragen ist. Dabei gibt es verschiedene Geltungsbereiche von projektbezogen bis unternehmensweit, und bei Namenskonflikten entscheidet eine feste Rangfolge, welcher Eintrag gilt.
TL;DR: Claude Code kann sich nicht mit einem MCP-Server verbinden, solange dieser Server nicht in der Konfiguration erscheint. Eine Definition kann privat für ein einzelnes Projekt sein, mit einem Team geteilt werden, überall für einen einzelnen Benutzer verfügbar sein oder von einer Organisation verwaltet werden. Wenn derselbe Servername in mehr als einem Geltungsbereich auftaucht, legt die Vorrangregel fest, welche vollständige Definition gewinnt. Nach der Konfiguration folgt eine separate Aufgabe: das Verbinden, der Handshake und das Aushandeln der Funktionen, die der Server tatsächlich unterstützt.
Im vorherigen Artikel haben wir einen internen Jira-Server als Anwendungsbeispiel verwendet. Wo sollte dieser Server deklariert werden, damit Claude Code weiß, dass er existiert?
Darauf gibt es keine einzige Antwort. Es hängt davon ab, wer den Server nutzen soll und welche Teile seiner Konfiguration gefahrlos geteilt werden können.
Angenommen, ein Unternehmen stellt einen MCP-Server für seine interne Jira-Instanz bereit. Alle Mitglieder eines Teams sollten ihn nutzen können, aber das API-Token von niemandem sollte in ein gemeinsames Repository kopiert werden.
Das ist das erste Konfigurationsproblem, das MCP lösen muss: Die Verbindungsdetails einer geteilten Funktion sollten einmal deklariert werden, während jede Person die Kontrolle über ihre privaten Zugangsdaten behalten kann.
Die aktuelle öffentliche Dokumentation von Claude Code beschreibt drei reguläre Installationsbereiche sowie die verwaltete Organisationskonfiguration:
Die Claude Code MCP-Referenz dokumentiert die Speicherorte und den vorgesehenen Verwendungszweck dieser Bereiche.
Der lokale Bereich ist im Szenario mit dem geteilten Jira besonders nützlich. Die.mcp.json des Projekts kann deklarieren: „Dieses Repository verwendet den Jira-Server“, während jeder Entwickler seine eigenen zugangsdatenhaltigen Konfigurationen privat bereitstellt. Das gemeinsame Repository etabliert die Integration; die lokale Konfiguration vervollständigt sie für eine einzelne Person.
Es gibt auch Serverquellen außerhalb dieser regulären Bereichshierarchie. Eine Sitzung kann eine temporäre Konfiguration über eine Kommandozeilenoption erhalten, und über Claude.ai konfigurierte Connectors können Claude Code erreichen. Das sind separate Wege, keine Ersatz-Alternativen zur üblichen Wahl zwischen Projekt, Benutzer und lokal.
Was geschieht, wenn derselbe Servername in der Projekt-, Benutzer- und lokalen Konfiguration auftaucht?
Claude Code löst diesen Konflikt vorhersehbar auf. Die öffentliche Vorrangreihenfolge lautet:
Organisationsverwaltete Serverdefinitionen haben Vorrang vor allen genannten, wenn sie einen Server duplizieren.
Das wichtige Detail ist leicht zu übersehen: Claude Code verwendet den gesamten Servereintrag aus der gewinnenden Quelle. Es führt keine einzelnen Felder aus mehreren Bereichen zu einem zusammengesetzten Datensatz zusammen. Dieser Unterschied macht das Debuggen weniger rätselhaft. Wenn eine lokale Definition denselben Servernamen wie eine Projektdefinition hat, wird Claude Code die lokale Definition verwenden; sie ist nicht lediglich ein Ort, um einen zusätzlichen Header an den Projektdatensatz anzuhängen.
Diese Vorrangregel ist praktisch und nicht willkürlich. Ein Team kann eine gemeinsame Basis in der.mcp.json festlegen, während eine Einzelperson einen expliziten Weg behält, um eine private oder projektspezifische Definition zu ersetzen. Wenn eine verwaltete Definition für denselben Server existiert, gewinnt stattdessen die Definition der Organisation.
Eine weitere Sicherung gilt speziell für projektbezogene Server. Eine.mcp.json-Datei reist in der Regel mit einem Repository mit, daher fragt Claude Code in interaktiven Sitzungen vor der Verwendung seiner projektbezogenen Server um Genehmigung. Dadurch werden der Verbindungsbefehl und die Argumente sichtbar, bevor ein geklontes Repository sie ausführen darf. Die Bereiche Benutzer und lokal sind bereits die private Konfiguration des Benutzers selbst, sodass sie keinen Genehmigungsschritt bei der ersten Verwendung benötigen.
Ein Konfigurationseintrag ist nur eine Erklärung, dass ein Server existieren sollte. Die tatsächliche Verbindung muss erst noch hergestellt werden.
Claude Code verfolgt den Verbindungszustand eines Servers, anstatt alles auf ein einzelnes Ja-oder-Nein-Flag zu reduzieren. Die Zustände unterscheiden einen verbundenen Server von einem, der keine Verbindung herstellen konnte, sich noch verbindet, deaktiviert ist oder eine Authentifizierung benötigt.
Diese Trennung ist wichtig, weil „nicht erreichbar“ und „erreichbar, aber nicht autorisiert“ zu unterschiedlichen Abhilfemaßnahmen führen. Eine fehlerhafte URL, ein fehlender Prozess oder ein abgestürzter Kindprozess ist ein Verbindungsproblem. Eine abgelaufene OAuth-Sitzung oder eine fehlende Berechtigung ist ein Authentifizierungsproblem. Beides als denselben generischen Fehler zu behandeln, würde die jeweils sinnvollste nächste Aktion verschleiern.
Die Verbindungsphase und ein späterer Tool-Aufruf verdienen zudem unterschiedliche Timeout-Erwartungen. Eine Verbindung, die innerhalb eines kurzen Zeitfensters nie antwortet, ist oft falsch konfiguriert oder läuft überhaupt nicht. Ein Tool-Aufruf hingegen kann den Server auffordern, eine lang andauernde Operation auszuführen. Ein Client sollte vermeiden, diese beiden Wartezeiten so zu behandeln, als hätten sie dieselbe Fehlerbedeutung.
Eine erfolgreiche Transportverbindung ist noch nicht das Ende des Einrichtungswegs. Claude Code muss noch erfahren, was der Server unterstützt.
Dies ist die Capability-Aushandlung. Client und Server deklarieren ihre unterstützten Funktionen, und der Client aktiviert nur die Funktionen, die der Server tatsächlich ankündigt. Ein Server könnte Tools anbieten, aber keine Ressourcen; ein anderer könnte lesbare Ressourcen bereitstellen, während er überhaupt keine aufrufbaren Tools anbietet.
Deshalb sollte MCP nicht einfach als „eine Möglichkeit, Tools hinzuzufügen“ beschrieben werden. Tools, Ressourcen und Prompts sind getrennte Funktionsfamilien. Die Einführung des Model Context Protocol stellt MCP als Standardverbindung zwischen KI-Anwendungen und externen Systemen dar, einschließlich Datenquellen, Tools und Workflows.
Die Aushandlung verhindert, dass diese Flexibilität zum Rätselraten wird:
Das Ergebnis ist eine bewusst bescheidene Regel: Verwende das, was der Server angibt zu unterstützen, statt anzunehmen, dass jeder Server jeden Teil des Protokolls implementiert.
Nachdem Handshake und Capability-Aushandlung abgeschlossen sind, ist der Server verbunden. Aber das bedeutet noch immer nicht, dass das Modell eine neue Aktion verwenden kann.
Die Verbindung stellt nur einen funktionierenden Kanal und einen vereinbarten Funktionsumfang her. Die nächsten Fragen lauten, wie Bytes über diesen Kanal bewegt werden und wie ein deklariertes Server-Tool zu einem normalen Eintrag in Claude Codes eigener Tool-Liste wird.
Das sind getrennte Transformationen, und ihre Trennung ist es, was das System beherrschbar macht:
Die Serienübersicht liefert die gesamte Pipeline, während Teil 1 erklärt, warum MCP überhaupt existiert.
Ein Handshake setzt voraus, dass Claude Code bereits weiß, wie es mit dem Server kommunizieren kann. Das kann bedeuten, einen lokalen Kindprozess zu starten und über Standard-Ein-/Ausgabe zu kommunizieren, oder Anfragen an einen entfernten Dienst über einen Netzwerktransport zu stellen.
Der nächste Artikel untersucht diese Transportwahl: welche Verbindungspfade das Protokoll standardisiert, welche Pfade Claude Code in der Praxis unterstützt und warum ein lokaler Prozess und ein entfernter Dienst nicht auf exakt dieselbe Weise wiederholt oder diagnostiziert werden sollten.
Automatisch übersetzt. Das Original auf Englisch ist unten aufklappbar.
Original (Englisch) anzeigen
TL;DR: Claude Code cannot connect to an MCP server until that server appears in configuration. A definition may be private to one project, shared with a team, available to one user everywhere, or managed by an organization. When the same server name appears in more than one scope, precedence determines which complete definition wins. After configuration comes a separate job: connecting, handshaking, and negotiating the capabilities that server actually supports.
In the previous article, we used an internal Jira server as the motivating example. Where should that server be declared so Claude Code knows it exists?
There is no single answer. It depends on who should use the server and which parts of its configuration are safe to share.
Suppose a company provides an MCP server for its internal Jira instance. Everyone on a team should be able to use it, but nobody’s API token should be copied into a shared repository.
That is the first configuration problem MCP needs to solve: the connection details for a shared capability should be declared once, while each person can retain control of their private credentials.
Claude Code’s current public documentation describes three regular installation scopes, plus organization-managed configuration:
The Claude Code MCP reference documents the storage locations and intended use of these scopes.
The local scope is particularly useful in the shared-Jira scenario. The project’s.mcp.json can declare “this repository uses the Jira server,” while each developer supplies their own credential-bearing configuration privately. The shared repository establishes the integration; the local configuration completes it for one person.
There are also server sources outside this regular scope hierarchy. A session can receive temporary configuration through a command-line option, and connectors configured through Claude.ai can reach Claude Code. Those are separate paths, not substitutes for the ordinary project/user/local choice.
What if the same server name appears in project, user, and local configuration?
Claude Code resolves that conflict predictably. The public precedence order is:
Organization-managed server definitions take precedence over all of those when they duplicate a server.
The important detail is easy to miss: Claude Code uses the entire server entry from the winning source. It does not merge individual fields from several scopes into one composite record. That distinction makes debugging less mysterious. If a local definition has the same server name as a project definition, the local definition is the one that Claude Code will use; it is not merely a place to append one extra header to the project record.
This precedence is practical rather than arbitrary. A team can establish a shared baseline in.mcp.json, while an individual retains an explicit way to substitute a private or project-specific definition. If a managed definition exists for the same server, the organization’s definition wins instead.
One more safeguard applies specifically to project-scoped servers. A.mcp.json file usually travels with a repository, so Claude Code asks for approval in interactive sessions before using its project-scoped servers. That makes the connection command and arguments visible before a cloned repository gets to run them. User and local scopes are already the user’s own private configuration, so they do not need the same first-use approval step.
A configuration record is only a declaration that a server should exist. The actual connection still has to be established.
Claude Code tracks a server’s connection state rather than reducing everything to a single yes-or-no flag. States distinguish a connected server from one that failed to connect, is still connecting, is disabled, or needs authentication.
That separation matters because “unreachable” and “reachable but unauthorized” lead to different remedies. A bad URL, missing process, or crashed child process is a connection problem. An expired OAuth session or missing permission is an authentication problem. Treating both as the same generic failure would hide the next useful action.
The connection phase and a later tool call also deserve different timeout expectations. A connection that never responds within a short window is often misconfigured or not running at all. A tool call, by contrast, may ask the server to perform a long-running operation. A client should avoid treating those two waits as if they had the same failure meaning.
A successful transport connection is not yet the end of the setup path. Claude Code still needs to learn what the server supports.
This is capability negotiation. Client and server declare their supported features, and the client enables only the capabilities the server actually advertises. A server might offer tools but no resources; another might expose readable resources while offering no callable tools at all.
That is why MCP should not be described simply as “a way to add tools.” Tools, resources, and prompts are distinct capability families. The Model Context Protocol introduction frames MCP as a standard connection between AI applications and external systems, including data sources, tools, and workflows.
Negotiation keeps that flexibility from becoming guesswork:
The result is an intentionally modest rule: use what the server says it supports, rather than assuming every server implements every part of the protocol.
After the handshake and capability negotiation complete, the server is connected. But that still does not mean the model can use a new action yet.
The connection only establishes a working channel and an agreed feature set. The next questions are how bytes move across that channel, and how a declared server tool becomes a normal entry in Claude Code’s own tool list.
Those are separate transformations, and separating them is what makes the system manageable:
The series map provides the broader pipeline, while Part 1 explains why MCP exists at all.
A handshake assumes Claude Code already knows how to speak to the server. That may mean launching a local child process and communicating over standard input/output, or making requests to a remote service over a network transport.
The next article examines that transport choice: which connection paths the protocol standardizes, which paths Claude Code supports in practice, and why a local process and a remote service should not be retried or diagnosed in exactly the same way.