MCP Connector Guide for Claude

Best Practices für das Erstellen, Einrichten und Deployen von MCP-Connectors in Claude.ai, Claude Desktop und Claude Code.

1. Überblick

MCP (Model Context Protocol) ist ein offener Standard (JSON-RPC 2.0), der AI-Clients (Claude, Cursor, VS Code, etc.) mit externen Tools über eine einheitliche Schnittstelle verbindet. Ein MCP-Server exponiert Tools, Resources und Prompts, die Claude zur Laufzeit entdeckt und aufruft.

Spec-Version: 2025-11-25 (aktuell) Transport: Streamable HTTP (remote) / stdio (lokal) Offizielle Spec: https://modelcontextprotocol.io/specification/2025-11-25

2. Architektur

┌─────────────┐    JSON-RPC 2.0     ┌─────────────┐     API Calls     ┌──────────┐
│  Claude.ai   │ ◄──────────────────► │  MCP Server  │ ◄───────────────► │  GitHub  │
│  (MCP Client)│   Streamable HTTP   │  (dein Code) │                   │  Slack   │
│              │                     │              │                   │  DB etc. │
└─────────────┘                     └─────────────┘                   └──────────┘

Primitives eines MCP-Servers:

Primitive	Zweck	Beispiel
Tool	Ausführbare Aktion, die das LLM aufrufen kann	`create_issue`, `search_repos`
Resource	Read-only Daten (URI-basiert)	`github://repos/{owner}/{repo}/readme`
Prompt	Wiederverwendbare Prompt-Templates	`summarize_pr`

3. Voraussetzungen

Claude-Plan: Pro, Max, Team oder Enterprise (Free: 1 Custom Connector)
SDK: TypeScript (@modelcontextprotocol/sdk) oder Python (mcp mit FastMCP)
Transport: Streamable HTTP für Remote-Server (HTTPS zwingend für Claude.ai)
Auth: OAuth 2.0 oder Bearer Token, je nach Zielservice

4. Technologie-Wahl

TypeScript (empfohlen für Production)

npm install @modelcontextprotocol/sdk zod

Vorteile: Type Safety via Zod-Schemas, native Streamable HTTP, ideal für Cloudflare Workers / Vercel Edge / Node.

Python (empfohlen für Prototyping)

pip install mcp

Vorteile: FastMCP-Decorators, Schema-Generierung aus Type Hints + Docstrings, schneller Einstieg.

Entscheidungshilfe

Kriterium	TypeScript	Python
Type Safety	Zod-Schemas (explizit, strikt)	Type Hints (implizit)
Prototyping-Speed	Mittel	Hoch (FastMCP)
Remote HTTP Deploy	Nativ (Edge, Workers)	FastAPI / uvicorn
Ecosystem	Node.js Infra	ML/Data Pipelines

5. MCP-Server bauen

5.1 TypeScript – Minimal-Beispiel

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

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

server.tool(
  "search_issues",
  "Search GitHub issues by query string",
  {
    repo: z.string().describe("owner/repo format"),
    query: z.string().describe("Search query"),
    state: z.enum(["open", "closed", "all"]).default("open"),
  },
  async ({ repo, query, state }) => {
    const response = await fetch(
      `https://api.github.com/search/issues?q=${encodeURIComponent(query)}+repo:${repo}+state:${state}`,
      { headers: { Authorization: `Bearer ${process.env.GITHUB_TOKEN}` } }
    );
    const data = await response.json();

    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(data.items?.map((i: any) => ({
            number: i.number,
            title: i.title,
            state: i.state,
            url: i.html_url,
          })), null, 2),
        },
      ],
    };
  }
);

5.2 Python – FastMCP Minimal-Beispiel

from mcp.server.fastmcp import FastMCP
import httpx

mcp = FastMCP("github-connector")

@mcp.tool()
async def search_issues(repo: str, query: str, state: str = "open") -> str:
    """Search GitHub issues in a repository.

    Args:
        repo: Repository in owner/repo format
        query: Search query string
        state: Issue state filter (open, closed, all)
    """
    async with httpx.AsyncClient() as client:
        resp = await client.get(
            "https://api.github.com/search/issues",
            params={"q": f"{query} repo:{repo} state:{state}"},
            headers={"Authorization": f"Bearer {os.environ['GITHUB_TOKEN']}"},
        )
        data = resp.json()
        return json.dumps([
            {"number": i["number"], "title": i["title"], "url": i["html_url"]}
            for i in data.get("items", [])
        ], indent=2)

if __name__ == "__main__":
    mcp.run(transport="streamable-http", host="0.0.0.0", port=8000)

6. Tool-Design Best Practices

6.1 Naming & Descriptions

Tool-Namen: snake_case, verb_noun-Pattern (create_issue, list_repos, search_pull_requests)
Descriptions: Klar, für das LLM geschrieben. Das LLM entscheidet anhand der Description, ob es das Tool aufruft. Keine Marketing-Sprache, keine Abkürzungen ohne Kontext.
Parameter-Descriptions: Jeder Parameter braucht eine .describe() (Zod) oder einen Docstring-Eintrag (Python). Format-Hinweise einbauen: "Repository in owner/repo format, e.g. 'anthropics/claude-code'"

6.2 Granularität

Ein Tool = eine Aktion. Kein God-Tool, das alles kann.
Lese- und Schreib-Operationen trennen: get_issue vs. update_issue
Suchbare Listen mit Filtern statt "gib mir alles": Pagination, Limit-Parameter

6.3 Error Handling

// GOOD: Return a structured error message
return {
  content: [{ type: "text", text: `Error: Repository '${repo}' not found (404)` }],
  isError: true,
};

// BAD: Throwing an uncontrolled exception can terminate the connection
throw new Error("Not found");

Fehler immer als isError: true Content zurückgeben, nie die Connection crashen lassen.
Actionable Error Messages: Was ist schiefgelaufen, was kann der User tun?

6.4 Structured Responses

JSON für maschinenlesbare Daten, Markdown für menschenlesbare Zusammenfassungen.
Große Payloads kürzen: Das LLM hat ein Kontextfenster. Keine 500-Issue-Listen zurückgeben → Pagination erzwingen.

7. Transport & Deployment

7.1 Streamable HTTP (Remote – für Claude.ai Connectors)

Der aktuelle Standard-Transport für Remote-Server. SSE (Server-Sent Events) ist deprecated seit MCP Spec 2025-03-26, wird aber noch für Backwards Compatibility unterstützt.

Anforderungen:

HTTPS zwingend (kein self-signed für Claude.ai)
Endpoint muss MCP Streamable HTTP implementieren
CORS-Header korrekt setzen, wenn der Server direkt aus dem Browser angesprochen wird

Deploy-Optionen:

Plattform	Stack	Anmerkung
Cloudflare Workers	TypeScript	Edge, global, günstig
Vercel Edge Functions	TypeScript	Gut für Next.js-Stacks
Fly.io	TypeScript / Python	Container-basiert, persistent
Railway / Render	Beliebig	Einfaches Container-Hosting
Eigener VPS (Nginx + Docker)	Beliebig	Volle Kontrolle

7.2 stdio (Lokal – für Claude Desktop / Claude Code)

Für lokale MCP-Server, die auf deiner Maschine laufen. Konfiguration über claude_desktop_config.json (Claude Desktop) oder claude mcp add (Claude Code).

Claude Desktop Config (~/.config/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
      }
    }
  }
}

Claude Code:

# HTTP remote server
claude mcp add-json github \
  '{"type":"http","url":"https://api.githubcopilot.com/mcp/","headers":{"Authorization":"Bearer YOUR_PAT"}}'

# Local stdio server
claude mcp add github -s user -- docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server

8. Authentifizierung

8.1 OAuth 2.0 (empfohlen für Claude.ai Connectors)

Claude.ai unterstützt OAuth-Flows bei Custom Connectors. Dein MCP-Server muss den OAuth-Dance implementieren, damit Claude den User beim Verbinden authentifizieren kann.

8.2 Bearer Token / PAT

Für lokale Server oder API-only-Setups. Token über Environment-Variable injizieren, nie hardcoden.

8.3 Security-Checkliste

Tokens nur über Env-Vars, nie im Code
Scopes minimal halten (Least Privilege)
Rate Limiting implementieren (das LLM ruft Tools aggressiv auf)
Input Validation auf allen Tool-Parametern (SQL Injection, Path Traversal)
Keine sensitiven Daten in Tool-Responses, die nicht angefragt wurden
Logging nur zu stderr/Files, nie stdout (bei stdio-Transport)

9. Connector in Claude.ai einrichten

9.1 Custom Connector hinzufügen

Claude.ai → Customize → Connectors (oder claude.ai/settings/connectors)
"+" → "Add custom connector"
Name: Sprechender Name (z.B. "GitHub – Production")
URL: HTTPS-URL deines MCP-Servers
Advanced Settings (optional):
- OAuth Client ID / Client Secret (wenn OAuth implementiert)
Authentifizieren (Browser-Popup für OAuth oder Token-Eingabe)

9.2 Bestehende Connectors aus dem Directory

Über 200 vorgefertigte Connectors im Directory verfügbar. Einige davon sind interaktiv (rendern UI im Chat): Figma, Canva, Asana, Slack, Box, etc.

9.3 GitHub-Connector speziell

Stand Juni 2026: Der offizielle GitHub MCP-Server (ghcr.io/github/github-mcp-server) erfordert OAuth über eine registrierte GitHub App. Das wird von Claude.ai Custom Connectors noch nicht nativ unterstützt. Workarounds:

Claude Desktop / Claude Code: Lokaler Docker-basierter stdio-Server mit PAT (funktioniert sofort, siehe Abschnitt 7.2)
Eigener Proxy: MCP-Server bauen, der PAT-Auth akzeptiert und GitHub API wrapped → als Custom Connector in Claude.ai einbinden
GitHub Copilot MCP Endpoint: https://api.githubcopilot.com/mcp/ mit Bearer PAT (funktioniert in Claude Code, experimentell in Claude.ai)

10. Testen

10.1 MCP Inspector

Das offizielle Debug-Tool für MCP-Server:

# TypeScript
npx @modelcontextprotocol/inspector node build/index.js

# Python
npx @modelcontextprotocol/inspector python your_server.py

Öffnet ein lokales Web-UI, in dem du Tools manuell aufrufen, den Handshake prüfen und Responses inspizieren kannst.

10.2 Checkliste vor Deployment

Alle Tools im Inspector einzeln getestet
Error Cases getestet (ungültige Parameter, Auth-Fehler, Rate Limits)
Response-Größen geprüft (keine Monster-Payloads)
Capability Negotiation korrekt (Server deklariert tools, resources, prompts)
Transport getestet (stdio lokal, Streamable HTTP remote)
CORS-Header korrekt (wenn Browser-basierter Client)

11. Production Checklist

Logging: stderr oder File, nie stdout (stdout ist der stdio-Transportkanal)
Error Handling: Jeder Tool-Call in try/catch, saubere Fehlermeldungen zurückgeben
Input Validation: Zod (TS) / Type Hints + explizite Checks (Python)
Rate Limiting: Das LLM ruft Tools in Bursts auf – externe API-Rate-Limits beachten
Idempotenz: Schreibende Tools sollten bei erneutem Aufruf nicht doppelt schreiben
Timeouts: Externe API-Calls mit Timeout versehen (LLM wartet nicht ewig)
Health Check: Endpoint für Monitoring bereitstellen
Versioning: Server-Version in McpServer Konstruktor setzen

12. Referenzen

Ressource	URL
MCP Specification	https://modelcontextprotocol.io/specification/2025-11-25
TypeScript SDK	https://github.com/modelcontextprotocol/typescript-sdk
Python SDK	https://github.com/modelcontextprotocol/python-sdk
MCP Inspector	`npx @modelcontextprotocol/inspector`
Claude Connectors Docs	https://support.claude.com/en/articles/11175166
Claude API MCP Connector	https://docs.claude.com/en/docs/agents-and-tools/mcp-connector
GitHub MCP Server	https://github.com/github/github-mcp-server
GitHub MCP Server Install (Claude)	https://github.com/github/github-mcp-server/blob/main/docs/installation-guides/install-claude.md

Dieses Dokument ist ein Entwurf und sollte vor externer Verwendung geprüft werden.

1. Überblick​

2. Architektur​

3. Voraussetzungen​

4. Technologie-Wahl​

TypeScript (empfohlen für Production)​

Python (empfohlen für Prototyping)​

Entscheidungshilfe​

5. MCP-Server bauen​

5.1 TypeScript – Minimal-Beispiel​

5.2 Python – FastMCP Minimal-Beispiel​

6. Tool-Design Best Practices​

6.1 Naming & Descriptions​

6.2 Granularität​

6.3 Error Handling​

6.4 Structured Responses​

7. Transport & Deployment​

7.1 Streamable HTTP (Remote – für Claude.ai Connectors)​

7.2 stdio (Lokal – für Claude Desktop / Claude Code)​

8. Authentifizierung​

8.1 OAuth 2.0 (empfohlen für Claude.ai Connectors)​

8.2 Bearer Token / PAT​

8.3 Security-Checkliste​

9. Connector in Claude.ai einrichten​

9.1 Custom Connector hinzufügen​

9.2 Bestehende Connectors aus dem Directory​

9.3 GitHub-Connector speziell​

10. Testen​

10.1 MCP Inspector​

10.2 Checkliste vor Deployment​

11. Production Checklist​

12. Referenzen​