DEV Community

Cover image for AI 에이전트 API 테스트 능력 부여하는 MCP 서버 구축 방법
Rihpig
Rihpig

Posted on Originally published at apidog.com

AI 에이전트 API 테스트 능력 부여하는 MCP 서버 구축 방법

#agents #api #mcp #testing

요약 (TL;DR)

run_test, validate_schema, list_environments 세 가지 도구를 노출하는 TypeScript MCP 서버를 빠르게 구축하세요. Claude Code는 ~/.claude/settings.json, Cursor는 .cursor/mcp.json에 MCP 서버를 등록합니다. 그러면 AI 에이전트가 채팅 인터페이스 내에서 Apidog 테스트 실행, OpenAPI 스키마 검증, 환경 목록 조회를 자동화할 수 있습니다. 전체 소스 코드는 약 150줄이며 @modelcontextprotocol/sdk 패키지를 활용합니다.

Apidog을 지금 사용해보세요

Claude Code, Cursor 및 기타 AI 에이전트가 채팅 인터페이스를 벗어나지 않고 Apidog API 테스트를 실행하고, 스키마를 검증하며, 응답을 비교할 수 있도록 MCP 서버를 직접 구축해보세요.

💡 실전 배경

코딩 세션 중에 AI 에이전트가 API 엔드포인트를 완성했다면, 복사-붙여넣기 없이 채팅에서 바로 Apidog 테스트를 실행하고 결과를 즉시 받아보고 싶을 것입니다.

이것이 바로 Model Context Protocol (MCP)의 역할입니다. MCP는 AI 에이전트가 표준 인터페이스로 외부 도구에 접근할 수 있도록 하며, Apidog MCP 서버를 사용하면 컨텍스트 전환 없이 테스트 실행, 스키마 검증, 환경 조회가 가능합니다.

MCP란 무엇인가요?

MCP(Model Context Protocol)는 AI 에이전트가 외부 도구 및 데이터 소스에 접근할 수 있도록 하는 표준 프로토콜입니다. Claude Code, Cursor 등 MCP 호환 클라이언트에서 동작하는 플러그인 시스템과 유사합니다.

MCP 서버는 도구(에이전트가 호출할 수 있는 함수)와 리소스(에이전트가 읽을 수 있는 데이터)를 노출합니다. 여기서는 API 테스트를 위한 Apidog MCP 서버의 도구 구현에 집중합니다.

┌─────────────────┐         ┌──────────────────┐         ┌─────────────┐
│  AI 에이전트    │         │  MCP 서버        │         │  Apidog     │
│  (Claude Code)  │◄───────►│  (사용자 코드)   │◄───────►│  API        │
└─────────────────┘   JSON  └──────────────────┘  HTTP   └─────────────┘
Enter fullscreen mode Exit fullscreen mode

1단계: 프로젝트 설정

새 TypeScript 프로젝트를 만듭니다.

mkdir apidog-mcp-server
cd apidog-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node
Enter fullscreen mode Exit fullscreen mode

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"]
}
Enter fullscreen mode Exit fullscreen mode

package.json에 빌드 및 실행 스크립트 추가:

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  }
}
Enter fullscreen mode Exit fullscreen mode

2단계: MCP 서버 스켈레톤 생성

src/index.ts 파일을 생성 후 기본 MCP 서버를 초기화합니다.

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: "AI 에이전트를 위한 Apidog API 테스트 도구"
});

// 도구는 아래에 정의합니다

const transport = new StdioServerTransport();
await server.connect(transport);
Enter fullscreen mode Exit fullscreen mode

이 코드는 MCP 서버를 생성하고 stdio를 통해 에이전트와 통신할 준비를 마칩니다.

3단계: run_test 도구 정의

src/index.ts에 API 테스트 실행용 도구를 추가합니다.

server.tool(
  "run_test",
  {
    projectId: z.string().describe("Apidog 프로젝트 ID (프로젝트 URL에서 찾을 수 있음)"),
    environmentId: z.string().optional().describe("선택적 환경 ID"),
    testSuiteId: z.string().optional().describe("선택적 테스트 스위트 ID")
  },
  async ({ projectId, environmentId, testSuiteId }) => {
    const apiKey = process.env.APIDOG_API_KEY;
    if (!apiKey) {
      return {
        content: [{ type: "text", text: "오류: APIDOG_API_KEY 환경 변수가 설정되지 않았습니다" }]
      };
    }

    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 오류: ${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: `요청 실패: ${error instanceof Error ? error.message : String(error)}` }]
      };
    }
  }
);
Enter fullscreen mode Exit fullscreen mode

도구 정의 구성

  1. 이름: run_test – 에이전트가 호출할 때 사용할 명확한 이름
  2. 파라미터 스키마: Zod로 유효성 검증. 설명 추가 권장
  3. 핸들러: Apidog API 호출 및 결과 반환

4단계: validate_schema 도구 추가

OpenAPI 3.x 스키마의 유효성을 검증하는 도구를 추가하세요.

server.tool(
  "validate_schema",
  {
    schema: z.object({}).describe("유효성 검사할 OpenAPI 3.x 스키마 객체"),
    strict: z.boolean().optional().default(false).describe("엄격 모드 사용 여부")
  },
  async ({ schema, strict }) => {
    const apiKey = process.env.APIDOG_API_KEY;
    if (!apiKey) {
      return {
        content: [{ type: "text", text: "오류: APIDOG_API_KEY 환경 변수가 설정되지 않았습니다" }]
      };
    }

    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: `유효성 검사 실패: ${JSON.stringify(result.errors, null, 2)}` }]
        };
      }

      return {
        content: [{
          type: "text",
          text: result.valid
            ? "스키마가 유효한 OpenAPI 3.x입니다"
            : `경고: ${JSON.stringify(result.warnings, null, 2)}`
        }]
      };
    } catch (error) {
      return {
        content: [{ type: "text", text: `유효성 검사 실패: ${error instanceof Error ? error.message : String(error)}` }]
      };
    }
  }
);
Enter fullscreen mode Exit fullscreen mode

5단계: list_environments 도구 추가

프로젝트의 테스트 환경 목록을 조회하는 도구를 구현합니다.

server.tool(
  "list_environments",
  {
    projectId: z.string().describe("Apidog 프로젝트 ID")
  },
  async ({ projectId }) => {
    const apiKey = process.env.APIDOG_API_KEY;
    if (!apiKey) {
      return {
        content: [{ type: "text", text: "오류: APIDOG_API_KEY 환경 변수가 설정되지 않았습니다" }]
      };
    }

    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 오류: ${response.status} ${error}` }]
        };
      }

      const environments = await response.json();
      return {
        content: [{
          type: "text",
          text: environments.length === 0
            ? "이 프로젝트에 대한 환경을 찾을 수 없습니다"
            : environments.map((e: any) =>
                `- ${e.name} (ID: ${e.id})${e.isDefault ? " [기본값]" : ""}`
              ).join("\n")
        }]
      };
    } catch (error) {
      return {
        content: [{ type: "text", text: `요청 실패: ${error instanceof Error ? error.message : String(error)}` }]
      };
    }
  }
);
Enter fullscreen mode Exit fullscreen mode

6단계: 빌드 및 테스트

서버 빌드:

npm run build
Enter fullscreen mode Exit fullscreen mode

간단한 MCP 클라이언트로 동작을 확인하세요. 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(`서버 출력: ${data}`);
});

server.stderr.on("data", (data) => {
  console.error(`서버 오류: ${data}`);
});

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");
Enter fullscreen mode Exit fullscreen mode

7단계: Claude Code 구성

MCP 서버를 Claude Code에 등록하세요.

~/.claude/settings.json 예시:

{
  "mcpServers": {
    "apidog": {
      "command": "node",
      "args": ["/absolute/path/to/apidog-mcp-server/dist/index.js"],
      "env": {
        "APIDOG_API_KEY": "your-api-key-here"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Claude Code를 재시작한 뒤, "API 테스트 지원"을 요청하면 Apidog 도구가 나타나야 합니다.

예시 사용법 (Claude Code):

run_test 도구를 사용하여 Apidog 프로젝트에서 테스트 실행
프로젝트 ID: proj_12345
환경: staging
Enter fullscreen mode Exit fullscreen mode 
이 OpenAPI 스키마를 Apidog 규칙에 따라 검증해줘
[스키마 붙여넣기]
Enter fullscreen mode Exit fullscreen mode 
proj_12345 프로젝트의 모든 환경을 나열해줘
Enter fullscreen mode Exit fullscreen mode

8단계: Cursor 구성

Cursor는 .cursor/mcp.json으로 MCP 서버를 연결합니다.

{
  "mcpServers": {
    "apidog": {
      "command": "node",
      "args": ["/absolute/path/to/apidog-mcp-server/dist/index.js"],
      "env": {
        "APIDOG_API_KEY": "your-api-key-here"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

예시 사용법 (Cursor):

@apidog run_test projectId="proj_12345" environmentId="staging"
Enter fullscreen mode Exit fullscreen mode

완전한 소스 코드

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: "AI 에이전트를 위한 Apidog API 테스트 도구"
});

// run_test 도구
server.tool(
  "run_test",
  {
    projectId: z.string().describe("Apidog 프로젝트 ID"),
    environmentId: z.string().optional().describe("환경 ID"),
    testSuiteId: z.string().optional().describe("테스트 스위트 ID")
  },
  async ({ projectId, environmentId, testSuiteId }) => {
    const apiKey = process.env.APIDOG_API_KEY;
    if (!apiKey) {
      return {
        content: [{ type: "text", text: "오류: APIDOG_API_KEY가 설정되지 않았습니다" }]
      };
    }

    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: `요청 실패: ${error instanceof Error ? error.message : String(error)}` }]
      };
    }
  }
);

// validate_schema 도구
server.tool(
  "validate_schema",
  {
    schema: z.object({}).describe("OpenAPI 스키마"),
    strict: z.boolean().optional().default(false)
  },
  async ({ schema, strict }) => {
    const apiKey = process.env.APIDOG_API_KEY;
    if (!apiKey) {
      return {
        content: [{ type: "text", text: "오류: APIDOG_API_KEY가 설정되지 않았습니다" }]
      };
    }

    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
          ? "스키마가 유효합니다"
          : `문제: ${JSON.stringify(result.errors || result.warnings, null, 2)}`
      }]
    };
  }
);

// list_environments 도구
server.tool(
  "list_environments",
  {
    projectId: z.string().describe("Apidog 프로젝트 ID")
  },
  async ({ projectId }) => {
    const apiKey = process.env.APIDOG_API_KEY;
    if (!apiKey) {
      return {
        content: [{ type: "text", text: "오류: APIDOG_API_KEY가 설정되지 않았습니다" }]
      };
    }

    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 ? " [기본값]" : ""}`
        ).join("\n")
      }]
    };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);
Enter fullscreen mode Exit fullscreen mode

구축한 것

구성 요소 목적
MCP 서버 AI 에이전트를 Apidog API에 연결
run_test 테스트 컬렉션을 프로그램적으로 실행
validate_schema 배포 전 OpenAPI 오류 포착
list_environments 사용 가능한 테스트 환경 검색
Zod 유효성 검사 타입 안정성 파라미터 처리
Stdio 트랜스포트 Claude Code, Cursor, 모든 MCP 클라이언트와 호환

다음 단계

서버 확장:

  • 환경 간 테스트 결과 비교용 compare_responses 도구 추가
  • 과거 실행 내역 조회용 get_test_history 도구 추가
  • 모의 엔드포인트 관리용 trigger_mock_server 도구 추가

운영 고려 사항:

  • 네트워크 불안정 시 재시도 로직 추가
  • API 스로틀링 방지를 위한 속도 제한 적용
  • 실패한 호출에 대한 로깅 추가
  • API 키를 안전하게 저장

팀과 공유:

  • @your-org/apidog-mcp-server로 npm에 배포
  • 환경 변수 및 구성법 문서화
  • 일반 MCP 클라이언트 예시 포함

일반적인 문제 해결

Claude Code에서 MCP 서버가 로드되지 않는 경우

  • ~/.claude/settings.json의 경로가 절대 경로인지 확인
  • node가 PATH에 있는지 (which node)
  • 빌드된 dist/index.js가 존재하는지 (ls -la dist/)
  • Claude Code의 MCP 로그에서 오류 확인

구성 후 도구가 나타나지 않음

  • Claude Code 완전 재시작
  • npm run build로 TypeScript 컴파일
  • 세 도구가 server.connect() 전에 정의되어 있는지 확인
  • 서버가 오류 없이 시작되는지 (node dist/index.js)

API 요청 401 오류

  • APIDOG_API_KEY 환경 변수 설정 확인
  • 공백, 따옴표 등 오타 없는지 확인
  • Apidog 계정에서 API 접근 권한 확인
  • 키를 curl로 직접 테스트 
  curl -H "Authorization: Bearer $APIDOG_API_KEY" https://api.apidog.com/v1/user
Enter fullscreen mode Exit fullscreen mode

Zod 유효성 검사 오류

  • 파라미터 이름과 스키마 일치 확인
  • 필수 필드 누락 없는지 확인
  • 선택 필드는 .optional() 사용
  • Zod 오류 메시지를 꼼꼼히 확인

TypeScript 컴파일 오류

  • 모든 의존성 설치 (npm install)
  • TypeScript 5.x 버전 확인 (npx tsc --version)
  • dist 폴더 삭제 후 재빌드 (rm -rf dist && npm run build)
  • 타입 불일치시 as 어설션 활용

MCP 서버 로컬에서 테스트하기

운영 배포 전, MCP 서버를 수동으로 stdio를 통해 검증하세요.

# 서버 시작
node dist/index.js

# 다른 터미널에서 도구 목록 요청
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.js
Enter fullscreen mode Exit fullscreen mode

예상 출력:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      { "name": "run_test", "description": "...", "inputSchema": {...} },
      { "name": "validate_schema", "description": "...", "inputSchema": {...} },
      { "name": "list_environments", "description": "...", "inputSchema": {...} }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

도구 호출 테스트:

echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_environments","arguments":{"projectId":"your-project-id"}}}' | node dist/index.js
Enter fullscreen mode Exit fullscreen mode

이제 AI 에이전트가 Apidog의 테스트 기능에 직접 접근할 수 있습니다.

브라우저 전환과 복사-붙여넣기 없이, 채팅에서 명령만 입력하면 결과를 받을 수 있습니다.

이것이 바로 MCP의 힘입니다.

AI 에이전트를 도메인별 도구로 확장해, 개발자의 반복 작업을 자동화하세요.

핵심 요약

  • MCP 서버는 AI 에이전트를 외부 API에 연결

    한 번 구축하면 Claude Code, Cursor, 기타 MCP 호환 클라이언트에서 사용 가능

  • 세 가지 도구로 대부분의 API 테스트 요구 충족

    실행(run_test), OpenAPI 유효성 검증(validate_schema), 환경 조회(list_environments)

  • Zod 유효성 검증으로 잘못된 파라미터 사전 차단

    타입 안정성으로 API 호출 전에 오류 포착

  • 도구별 구성

    Claude Code는 ~/.claude/settings.json, Cursor는 .cursor/mcp.json 사용

  • 운영 환경에선 오류 처리 필수

    재시도, 속도 제한, 안전한 키 저장소 등 보강 필요

자주 묻는 질문 (FAQ)

Q. AI에서 MCP란 무엇인가요?

A. MCP(Model Context Protocol)는 AI 에이전트가 외부 도구/데이터 소스에 접근할 수 있도록 하는 표준 프로토콜입니다. 플러그인 시스템과 유사합니다.

Q. Apidog용 MCP 서버는 어떻게 생성하나요?

A. @modelcontextprotocol/sdk 설치 → Zod로 도구 파라미터 정의 → Apidog API 호출하는 핸들러 작성 → StdioServerTransport로 연결

Q. Cursor와 함께 사용할 수 있나요?

A. 네, 프로젝트 루트의 .cursor/mcp.json에 MCP 서버 구성을 추가하면 Claude Code, Cursor 등에서 동일하게 동작합니다.

Q. 어떤 도구를 노출해야 하나요?

A. 최소한 run_test(테스트 실행), validate_schema(OpenAPI 검증), list_environments(환경 조회)를 구현하세요.

Q. Apidog MCP 서버는 운영 환경에 준비되었나요?

A. 튜토리얼 코드는 시작점입니다. 운영에서는 재시도, 속도 제한, 오류 처리, 안전한 API 키 저장을 반드시 추가하세요.

Q. Apidog API 키가 필요한가요?

A. 네. APIDOG_API_KEY를 환경 변수로 지정해야 하며, 서버는 이를 사용해 Apidog API를 인증합니다.

Q. 이 MCP 서버를 팀과 공유할 수 있나요?

A. 네. npm에 비공개 패키지로 배포하고, 환경 변수 및 구성 예시를 문서화하세요.

Top comments (0)