TL;DR
Erstellen Sie einen MCP-Server mit TypeScript, der drei Tools bereitstellt: run_test, validate_schema und list_environments. Konfigurieren Sie ihn in ~/.claude/settings.json für Claude Code oder .cursor/mcp.json für Cursor. Ihre KI-Agenten können dann Apidog-Tests ausführen, OpenAPI-Schemas validieren und Umgebungen abrufen, ohne die Chat-Oberfläche zu verlassen. Der vollständige Quellcode umfasst etwa 150 Zeilen und verwendet das Paket @modelcontextprotocol/sdk.
Erstellen Sie einen MCP-Server, mit dem Claude Code, Cursor und andere KI-Agenten Apidog-API-Tests ausführen, Schemas validieren und Antworten vergleichen können, alles ohne ihre Chat-Oberfläche zu verlassen.
Das ermöglicht das Model Context Protocol (MCP). MCP ermöglicht es KI-Agenten, über eine standardisierte Schnittstelle auf externe Tools zuzugreifen. Erstellen Sie einen MCP-Server für Apidog, und Ihr KI-Agent kann Tests ausführen, Schemas validieren und Umgebungen abrufen, ohne den Kontext zu wechseln.
Was ist MCP?
MCP (Model Context Protocol) ist ein Protokoll, das es KI-Agenten ermöglicht, auf externe Tools und Datenquellen zuzugreifen. Stellen Sie es sich als ein Plugin-System vor, das über Claude Code, Cursor und andere MCP-kompatible Clients hinweg funktioniert.
Ein MCP-Server stellt Tools (Funktionen, die der Agent aufrufen kann) und Ressourcen (Daten, die der Agent lesen kann) bereit. Ihr Apidog-MCP-Server wird Tools für API-Tests bereitstellen.
┌─────────────────┐ ┌──────────────────┐ ┌─────────────┐
│ KI-Agent │ │ MCP-Server │ │ Apidog │
│ (Claude Code) │◄───────►│ (Ihr Code) │◄───────►│ API │
└─────────────────┘ JSON └──────────────────┘ HTTP └─────────────┘
Schritt 1: Projekt einrichten
Erstellen Sie ein neues TypeScript-Projekt:
mkdir apidog-mcp-server
cd apidog-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node
Erstellen Sie tsconfig.json:
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"outDir": "./dist",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
},
"include": ["src/**/*"],
"exclude": ["node_modules"]
}
Fügen Sie ein Build-Skript zu package.json hinzu:
{
"scripts": {
"build": "tsc",
"start": "node dist/index.js"
}
}
Schritt 2: Das MCP-Server-Gerüst erstellen
Erstellen Sie src/index.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: "apidog",
version: "1.0.0",
description: "Apidog API-Test-Tools für KI-Agenten" // Apidog API testing tools for AI agents
});
// Tools werden hier definiert
const transport = new StdioServerTransport();
await server.connect(transport);
Dieses Gerüst erstellt einen MCP-Server und verbindet ihn mit dem Stdio-Transport. Der Transport wickelt die Kommunikation zwischen dem KI-Agenten und Ihrem Server über Standard-Ein-/Ausgabe ab.
Schritt 3: Das `run_test`-Tool definieren
Fügen Sie das erste Tool zu src/index.ts hinzu:
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: "apidog",
version: "1.0.0",
description: "Apidog API-Test-Tools für KI-Agenten" // Apidog API testing tools for AI agents
});
// Tool: run_test
server.tool(
"run_test",
{
projectId: z.string().describe("Apidog Projekt-ID (zu finden in der Projekt-URL)"), // Apidog project ID (found in project URL)
environmentId: z.string().optional().describe("Optionale Umgebungs-ID für die Testausführung"), // Optional environment ID for test execution
testSuiteId: z.string().optional().describe("Optionale Testsuiten-ID zur Ausführung einer spezifischen Suite") // Optional test suite ID to run specific suite
},
async ({ projectId, environmentId, testSuiteId }) => {
const apiKey = process.env.APIDOG_API_KEY;
if (!apiKey) {
return {
content: [{
type: "text",
text: "Fehler: Umgebungsvariable APIDOG_API_KEY ist nicht gesetzt" // Error: APIDOG_API_KEY environment variable not set
}]
};
}
// API-URL erstellen
let url = `https://api.apidog.com/v1/projects/${projectId}/tests/run`;
const params = new URLSearchParams();
if (environmentId) params.append("environmentId", environmentId);
if (testSuiteId) params.append("testSuiteId", testSuiteId);
if (params.toString()) url += `?${params.toString()}`;
try {
const response = await fetch(url, {
method: "POST",
headers: {
"Authorization": `Bearer ${apiKey}`,
"Content-Type": "application/json"
}
});
if (!response.ok) {
const error = await response.text();
return {
content: [{
type: "text",
text: `API-Fehler: ${response.status} ${error}` // API Error: ${response.status} ${error}
}]
};
}
const results = await response.json();
return {
content: [{
type: "text",
text: JSON.stringify(results, null, 2)
}]
};
} catch (error) {
return {
content: [{
type: "text",
text: `Anfrage fehlgeschlagen: ${error instanceof Error ? error.message : String(error)}` // Request failed: ${error instanceof Error ? error.message : String(error)}
}]
};
}
}
);
const transport = new StdioServerTransport();
await server.connect(transport);
Die Tool-Definition besteht aus drei Teilen:
- Name —
run_test(Agenten wählen Tools nach Namen aus, machen Sie ihn also beschreibend) - Schema — Zod-Validierung für Parameter mit Beschreibungen
- Handler — Asynchrone Funktion, die die Apidog-API aufruft
Schritt 4: Das `validate_schema`-Tool hinzufügen
Fügen Sie die Schema-Validierung hinzu, um OpenAPI-Fehler vor der Bereitstellung abzufangen:
// Tool: validate_schema
server.tool(
"validate_schema",
{
schema: z.object({}).describe("OpenAPI 3.x Schema-Objekt zur Validierung"), // OpenAPI 3.x schema object to validate
strict: z.boolean().optional().default(false).describe("Strengen Modus für zusätzliche Prüfungen aktivieren") // Enable strict mode for additional checks
},
async ({ schema, strict }) => {
const apiKey = process.env.APIDOG_API_KEY;
if (!apiKey) {
return {
content: [{
type: "text",
text: "Fehler: Umgebungsvariable APIDOG_API_KEY ist nicht gesetzt" // Error: APIDOG_API_KEY environment variable not set
}]
};
}
try {
const response = await fetch("https://api.apidog.com/v1/schemas/validate", {
method: "POST",
headers: {
"Authorization": `Bearer ${apiKey}`,
"Content-Type": "application/json"
},
body: JSON.stringify({ schema, strict })
});
const result = await response.json();
if (!response.ok) {
return {
content: [{
type: "text",
text: `Validierung fehlgeschlagen: ${JSON.stringify(result.errors, null, 2)}` // Validation failed: ${JSON.stringify(result.errors, null, 2)}
}]
};
}
return {
content: [{
type: "text",
text: result.valid
? "Schema ist gültiges OpenAPI 3.x" // Schema is valid OpenAPI 3.x
: `Warnungen: ${JSON.stringify(result.warnings, null, 2)}` // Warnings: ${JSON.stringify(result.warnings, null, 2)}
}]
};
} catch (error) {
return {
content: [{
type: "text",
text: `Validierung fehlgeschlagen: ${error instanceof Error ? error.message : String(error)}` // Validation failed: ${error instanceof Error ? error.message : String(error)}
}]
};
}
}
);
Schritt 5: Das `list_environments`-Tool hinzufügen
Fügen Sie ein Tool hinzu, um verfügbare Testumgebungen abzurufen:
// Tool: list_environments
server.tool(
"list_environments",
{
projectId: z.string().describe("Apidog Projekt-ID") // Apidog project ID
},
async ({ projectId }) => {
const apiKey = process.env.APIDOG_API_KEY;
if (!apiKey) {
return {
content: [{
type: "text",
text: "Fehler: Umgebungsvariable APIDOG_API_KEY ist nicht gesetzt" // Error: APIDOG_API_KEY environment variable not set
}]
};
}
try {
const response = await fetch(
`https://api.apidog.com/v1/projects/${projectId}/environments`,
{
headers: {
"Authorization": `Bearer ${apiKey}`
}
}
);
if (!response.ok) {
const error = await response.text();
return {
content: [{
type: "text",
text: `API-Fehler: ${response.status} ${error}` // API Error: ${response.status} ${error}
}]
};
}
const environments = await response.json();
return {
content: [{
type: "text",
text: environments.length === 0
? "Keine Umgebungen für dieses Projekt gefunden" // No environments found for this project
: environments.map((e: any) =>
`- ${e.name} (ID: ${e.id})${e.isDefault ? " [Standard]" : ""}` // - ${e.name} (ID: ${e.id})${e.isDefault ? " [default]" : ""}
).join("\n")
}]
};
} catch (error) {
return {
content: [{
type: "text",
text: `Anfrage fehlgeschlagen: ${error instanceof Error ? error.message : String(error)}` // Request failed: ${error instanceof Error ? error.message : String(error)}
}]
};
}
}
);
Schritt 6: Build und Test
Erstellen Sie den Server:
npm run build
Testen Sie mit einem einfachen MCP-Client. Erstellen Sie test-client.js:
import { spawn } from "child_process";
const server = spawn("node", ["dist/index.js"], {
env: { ...process.env, APIDOG_API_KEY: "your-api-key" }
});
server.stdout.on("data", (data) => {
console.log(`Server-Ausgabe: ${data}`); // Server output: ${data}
});
server.stderr.on("data", (data) => {
console.error(`Server-Fehler: ${data}`); // Server error: ${data}
});
// Senden Sie eine Testnachricht
const message = {
jsonrpc: "2.0",
id: 1,
method: "initialize",
params: {
protocolVersion: "2024-11-05",
capabilities: {},
clientInfo: { name: "test-client", version: "1.0.0" }
}
};
server.stdin.write(JSON.stringify(message) + "\n");
Schritt 7: Für Claude Code konfigurieren
Fügen Sie den MCP-Server zu Ihrer Claude Code-Konfiguration hinzu:
Erstellen oder bearbeiten Sie ~/.claude/settings.json:
{
"mcpServers": {
"apidog": {
"command": "node",
"args": ["/absolute/path/to/apidog-mcp-server/dist/index.js"],
"env": {
"APIDOG_API_KEY": "Ihr-API-Schlüssel-hier" // your-api-key-here
}
}
}
}
Starten Sie Claude Code neu. Die Apidog-Tools sollten nun erscheinen, wenn Sie Hilfe beim API-Test anfordern.
Verwendung in Claude Code:
Verwenden Sie das run_test-Tool, um Tests in meinem Apidog-Projekt auszuführen.
Projekt-ID: proj_12345
Umgebung: staging
Validieren Sie dieses OpenAPI-Schema anhand der Apidog-Regeln:
[Schema hier einfügen]
Listen Sie alle Umgebungen für das Projekt proj_12345 auf
Schritt 8: Für Cursor konfigurieren
Cursor verwendet eine ähnliche MCP-Konfiguration. Erstellen Sie .cursor/mcp.json in Ihrem Projekt:
{
"mcpServers": {
"apidog": {
"command": "node",
"args": ["/absolute/path/to/apidog-mcp-server/dist/index.js"],
"env": {
"APIDOG_API_KEY": "Ihr-API-Schlüssel-hier" // your-api-key-here
}
}
}
}
Verwendung in Cursor:
@apidog run_test projectId="proj_12345" environmentId="staging"
Vollständiger Quellcode
Hier ist die vollständige src/index.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: "apidog",
version: "1.0.0",
description: "Apidog API-Test-Tools für KI-Agenten" // Apidog API testing tools for AI agents
});
// Tool: run_test
server.tool(
"run_test",
{
projectId: z.string().describe("Apidog Projekt-ID"), // Apidog project ID
environmentId: z.string().optional().describe("Umgebungs-ID"), // Environment ID
testSuiteId: z.string().optional().describe("Testsuiten-ID") // Test suite ID
},
async ({ projectId, environmentId, testSuiteId }) => {
const apiKey = process.env.APIDOG_API_KEY;
if (!apiKey) {
return {
content: [{
type: "text",
text: "Fehler: APIDOG_API_KEY ist nicht gesetzt" // Error: APIDOG_API_KEY not set
}]
};
}
let url = `https://api.apidog.com/v1/projects/${projectId}/tests/run`;
const params = new URLSearchParams();
if (environmentId) params.append("environmentId", environmentId);
if (testSuiteId) params.append("testSuiteId", testSuiteId);
if (params.toString()) url += `?${params.toString()}`;
try {
const response = await fetch(url, {
method: "POST",
headers: {
"Authorization": `Bearer ${apiKey}`,
"Content-Type": "application/json"
}
});
const results = await response.json();
return {
content: [{
type: "text",
text: JSON.stringify(results, null, 2)
}]
};
} catch (error) {
return {
content: [{
type: "text",
text: `Anfrage fehlgeschlagen: ${error instanceof Error ? error.message : String(error)}` // Request failed: ${error instanceof Error ? error.message : String(error)}
}]
};
}
}
);
// Tool: validate_schema
server.tool(
"validate_schema",
{
schema: z.object({}).describe("OpenAPI-Schema"), // OpenAPI schema
strict: z.boolean().optional().default(false)
},
async ({ schema, strict }) => {
const apiKey = process.env.APIDOG_API_KEY;
if (!apiKey) {
return {
content: [{
type: "text",
text: "Fehler: APIDOG_API_KEY ist nicht gesetzt" // Error: APIDOG_API_KEY not set
}]
};
}
const response = await fetch("https://api.apidog.com/v1/schemas/validate", {
method: "POST",
headers: {
"Authorization": `Bearer ${apiKey}`,
"Content-Type": "application/json"
},
body: JSON.stringify({ schema, strict })
});
const result = await response.json();
return {
content: [{
type: "text",
text: result.valid
? "Schema ist gültig" // Schema is valid
: `Probleme: ${JSON.stringify(result.errors || result.warnings, null, 2)}` // Issues: ${JSON.stringify(result.errors || result.warnings, null, 2)}
}]
};
}
);
// Tool: list_environments
server.tool(
"list_environments",
{
projectId: z.string().describe("Apidog Projekt-ID") // Apidog project ID
},
async ({ projectId }) => {
const apiKey = process.env.APIDOG_API_KEY;
if (!apiKey) {
return {
content: [{
type: "text",
text: "Fehler: APIDOG_API_KEY ist nicht gesetzt" // Error: APIDOG_API_KEY not set
}]
};
}
const response = await fetch(
`https://api.apidog.com/v1/projects/${projectId}/environments`,
{
headers: { "Authorization": `Bearer ${apiKey}` }
}
);
const environments = await response.json();
return {
content: [{
type: "text",
text: environments.map((e: any) =>
`- ${e.name} (${e.id})${e.isDefault ? " [Standard]" : ""}` // - ${e.name} (${e.id})${e.isDefault ? " [default]" : ""}
).join("\n")
}]
};
}
);
const transport = new StdioServerTransport();
await server.connect(transport);
Was Sie erstellt haben
| Komponente | Zweck |
|---|---|
| MCP-Server | Verbindet KI-Agenten mit der Apidog-API |
run_test |
Testsammlungen programmatisch ausführen |
validate_schema |
OpenAPI-Fehler vor der Bereitstellung abfangen |
list_environments |
Verfügbare Testumgebungen entdecken |
| Zod-Validierung | Typsichere Parameterbehandlung |
| Stdio-Transport | Funktioniert mit Claude Code, Cursor, jedem MCP-Client |
Nächste Schritte
Erweitern Sie den Server:
- Fügen Sie das
compare_responses-Tool hinzu, um Testergebnisse über Umgebungen hinweg zu vergleichen - Fügen Sie
get_test_historyhinzu, um historische Testläufe abzurufen - Fügen Sie
trigger_mock_serverhinzu, um Mock-Endpunkte zu starten/stoppen
Überlegungen für die Produktion:
- Fügen Sie eine Wiederholungslogik für instabile Netzwerkanfragen hinzu
- Implementieren Sie Ratenbegrenzung, um API-Drosselung zu vermeiden
- Fügen Sie Protokollierung für die Fehlersuche bei fehlgeschlagenen Tool-Aufrufen hinzu
- Speichern Sie API-Schlüssel in einem sicheren Tresor anstelle von Umgebungsvariablen
Teilen Sie es mit Ihrem Team:
- Veröffentlichen Sie es auf npm als
@your-org/apidog-mcp-server - Dokumentieren Sie die benötigten Umgebungsvariablen
- Fügen Sie Beispiel-MCP-Konfigurationen für gängige Clients hinzu
Behebung häufiger Probleme
MCP-Server lädt nicht in Claude Code:
- Überprüfen Sie, ob der Pfad in
~/.claude/settings.jsonabsolut ist (nicht relativ) - Überprüfen Sie, ob
nodein Ihrem PATH ist:which node - Stellen Sie sicher, dass die gebaute
dist/index.jsexistiert:ls -la dist/ - Suchen Sie nach Fehlern in den MCP-Protokollen von Claude Code
Tools erscheinen nicht nach der Konfiguration:
- Starten Sie Claude Code komplett neu (beenden und wieder öffnen)
- Führen Sie
npm run buildaus, um sicherzustellen, dass TypeScript kompiliert wird - Überprüfen Sie, ob alle drei Tools vor
server.connect()definiert sind - Überprüfen Sie, ob der Server fehlerfrei startet:
node dist/index.js
API-Anfragen schlagen mit 401 fehl:
- Bestätigen Sie, dass
APIDOG_API_KEYin der Konfiguration gesetzt ist - Überprüfen Sie auf zusätzliche Leerzeichen oder Anführungszeichen um den Schlüsselwert
- Überprüfen Sie, ob Ihr Apidog-Konto API-Zugriff aktiviert hat
- Testen Sie den Schlüssel manuell:
curl -H "Authorization: Bearer $APIDOG_API_KEY" https://api.apidog.com/v1/user
Zod-Validierungsfehler:
- Stellen Sie sicher, dass die Parameternamen exakt mit dem Schema übereinstimmen
- Überprüfen Sie, ob erforderliche Felder bereitgestellt werden (keine Tippfehler bei
projectId) - Überprüfen Sie, ob optionale Felder `.optional()` im Schema verwenden
- Lesen Sie die vollständige Fehlermeldung – Zod zeigt Ihnen, welches Feld fehlgeschlagen ist
TypeScript-Kompilierungsfehler:
- Führen Sie
npm installaus, um sicherzustellen, dass alle Abhängigkeiten installiert sind - Überprüfen Sie die TypeScript-Version:
npx tsc --version(sollte 5.x sein) - Löschen und neu erstellen:
rm -rf dist && npm run build - Suchen Sie nach Typeninkonsistenzen in Fetch-Antworten (fügen Sie
as-Typzusicherungen hinzu)
Lokales Testen Ihres MCP-Servers
Bevor Sie in Produktion gehen, testen Sie Ihren Server lokal:
Manuelles Testen mit Stdio:
# Starten Sie den Server
node dist/index.js
# Senden Sie in einem anderen Terminal eine Testnachricht
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.js
Erwartete Ausgabe:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"tools": [
{ "name": "run_test", "description": "...", "inputSchema": {...} },
{ "name": "validate_schema", "description": "...", "inputSchema": {...} },
{ "name": "list_environments", "description": "...", "inputSchema": {...} }
]
}
}
Testen Sie einen Tool-Aufruf:
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_environments","arguments":{"projectId":"Ihre-Projekt-ID"}}}' | node dist/index.js
Ihre KI-Agenten haben jetzt direkten Zugriff auf die Testfunktionen von Apidog. Kein Kopieren und Einfügen mehr zwischen Chat und Browser. Keine manuellen Testläufe mehr. Geben Sie einen Befehl ein, erhalten Sie Ergebnisse zurück.
Das ist die Stärke von MCP: Erweitern Sie Ihre KI-Agenten mit domänenspezifischen Tools und lassen Sie sie das tun, wofür sie da sind – Ihnen helfen, schneller zu liefern.
Wichtige Erkenntnisse
- MCP-Server verbinden KI-Agenten mit externen APIs – Einmal erstellen, über Claude Code, Cursor und jeden MCP-kompatiblen Client verwenden
- Drei Tools decken die meisten API-Testanforderungen ab –
run_testfür die Ausführung,validate_schemafür die OpenAPI-Validierung,list_environmentsfür die Erkennung - Zod-Validierung verhindert fehlerhafte Parameter – Typsichere Tool-Definitionen fangen Fehler vor API-Aufrufen ab
- Die Konfiguration ist werkzeugspezifisch – Claude Code verwendet
~/.claude/settings.json, Cursor verwendet.cursor/mcp.json - Produktion erfordert Fehlerbehandlung – Fügen Sie Wiederholungslogik, Ratenbegrenzung und sichere Schlüsselspeicherung hinzu, bevor Sie bereitstellen
Häufig gestellte Fragen (FAQ)
Was ist MCP in der KI?MCP (Model Context Protocol) ist ein standardisiertes Protokoll, das es KI-Agenten ermöglicht, auf externe Tools und Datenquellen zuzugreifen. Stellen Sie es sich als ein Plugin-System für KI-Agenten vor.
Wie erstelle ich einen MCP-Server für Apidog?Installieren Sie @modelcontextprotocol/sdk, definieren Sie Tools mit Zod-Validierung, implementieren Sie Handler, die die Apidog-API aufrufen, und verbinden Sie sich über StdioServerTransport.
Kann ich dies mit Cursor verwenden?Ja. Fügen Sie die MCP-Server-Konfiguration zu .cursor/mcp.json in Ihrem Projektstammverzeichnis hinzu. Derselbe Server funktioniert mit Claude Code, Cursor und anderen MCP-Clients.
Welche Tools sollte ich bereitstellen?Beginnen Sie mit run_test zum Ausführen von Testsammlungen, validate_schema zur OpenAPI-Validierung und list_environments zum Abrufen verfügbarer Umgebungen.
Ist der Apidog MCP-Server produktionsreif?Der Tutorial-Code ist ein Ausgangspunkt. Fügen Sie Wiederholungslogik, Ratenbegrenzung, ordnungsgemäße Fehlerbehandlung und sichere API-Schlüsselspeicherung hinzu, bevor Sie ihn in Produktion verwenden.
Benötige ich einen Apidog API-Schlüssel?Ja. Setzen Sie APIDOG_API_KEY als Umgebungsvariable. Der Server liest dies zur Laufzeit, um API-Anfragen zu authentifizieren.
Kann ich diesen MCP-Server mit meinem Team teilen?Ja. Veröffentlichen Sie ihn auf npm als privates Paket, dokumentieren Sie die erforderlichen Umgebungsvariablen und fügen Sie Beispiel-MCP-Konfigurationen hinzu.
