mcp-link: REST API를 MCP 서버로 변환하기

"Claude한테 우리 ERP 조회를 시킬 수 없을까?" 사내 REST API를 AI 에이전트와 연결하고 싶은 개발자라면 한 번쯤 해본 질문입니다. 시스템은 이미 잘 만들어져 있고, AI 에이전트도 있는데, 둘 사이를 이어주는 연결고리만 없습니다.

문제는 연결 방식입니다. AI 에이전트는 REST API를 직접 이해하지 못합니다. MCP(Model Context Protocol)라는 표준 형식으로 포장된 도구만 사용할 수 있습니다. 결국 기존 REST API마다 MCP 서버를 새로 만들어야 하는데, 엔드포인트가 수십 개라면 이 작업만으로 며칠이 걸립니다.

mcp-link는 이 변환을 자동화합니다. API 설계 문서(OpenAPI 스펙)를 입력하면 그 API의 모든 기능이 AI 도구로 바뀝니다. 설계 문서가 없는 레거시 API도 AI로 문서를 먼저 만들면 같은 방법으로 연결할 수 있습니다.

1. mcp-link란?

mcp-link는 OpenAPI V3 스펙(Linux Foundation에서 정의한 REST API 표준 명세)을 MCP(Model Context Protocol) 서버로 자동 변환하는 Go 기반 도구입니다.

"OpenAPI 스펙만 있으면 모든 REST API가 즉시 AI 에이전트의 도구가 된다"

MCP는 Anthropic이 제안한 표준 프로토콜로, AI 에이전트가 외부 도구와 통신하는 방식을 정의합니다. Claude, Cursor, Windsurf 같은 AI 에이전트들이 이 표준을 지원하는데, 문제는 세상의 수천 개 REST API가 아직 MCP 서버를 갖고 있지 않다는 점입니다. mcp-link는 이 간극을 메웁니다.

2. 왜 MCP 서버를 직접 만들면 힘든가?

API마다 MCP 서버를 따로 만들어야 한다

Slack API를 연결하려면 Slack용 MCP 서버, Notion을 연결하려면 Notion용 MCP 서버를 만들어야 합니다. 각 엔드포인트를 MCP 도구 스키마(이름·설명·파라미터 타입)로 변환하고, 인증 방식(API Key, Bearer Token)을 개별 처리하며, 응답 형식을 MCP 표준에 맞게 직렬화합니다. 이 작업은 어떤 API든 거의 동일하게 반복됩니다.

업스트림 변경에 취약하다

API가 업데이트돼 새 엔드포인트가 추가되거나 파라미터가 바뀌면, MCP 서버 코드를 다시 수정해야 합니다. OpenAPI 스펙이 이미 그 변경 정보를 담고 있는데도 별도로 유지보수해야 합니다.

MCP 스펙 자체가 신규 표준이다

MCP 스펙은 2024년에 나왔습니다. 레퍼런스 구현이 많지 않아 직접 만들 때 각 필드의 의미나 SSE(Server-Sent Events) 연결 방식을 처음부터 파악해야 합니다.

3. 내부 구조: 어떻게 동작하는가?

핵심 아키텍처

mcp-link는 세 가지를 입력받아 SSE 엔드포인트를 노출합니다.

[OpenAPI 스펙 URL]  +  [API 베이스 URL]  +  [인증 헤더]
                         ↓
                    mcp-link 서버
                         ↓
         http://localhost:8080/sse?s=...&u=...&h=...
                         ↓
            AI 에이전트 (Claude, Cursor 등)

1. 스펙 파싱: OpenAPI V3 스펙 URL을 읽어 모든 경로(path), HTTP 메서드, 파라미터 타입, 설명을 파싱합니다.
2. MCP 도구 생성: 각 엔드포인트를 MCP 도구로 변환합니다. GET /users/{id} → getUser 도구, 파라미터 타입은 OpenAPI 스키마에서 그대로 가져옵니다.
3. SSE 서버 노출: 변환된 도구 목록을 SSE(Server-Sent Events) 방식으로 노출합니다. SSE는 서버가 연결을 열어두고 클라이언트에게 데이터를 실시간으로 밀어주는 방식입니다. AI 에이전트는 이 URL 하나를 mcpServers 설정에 등록하면 됩니다.
4. 요청 프록시: 에이전트가 도구를 호출하면 mcp-link가 원본 REST API로 HTTP 요청을 프록시합니다. 인증 헤더는 h= 파라미터로 자동으로 붙입니다.

경로 필터링

모든 엔드포인트가 필요하지 않을 때는 f= 파라미터로 포함·제외를 제어합니다.

f=+/messages/**,-/admin/**

+는 포함, -는 제외이며 와일드카드(**)를 지원합니다. Slack API에서 메시지 전송 엔드포인트만 노출하고 관리자 API는 숨기는 식으로 씁니다.

4. 직접 해보기

실습 대상은 JSONPlaceholder(https://jsonplaceholder.typicode.com)입니다. 개발자에게 익숙한 무료 테스트 REST API로, 공식 OpenAPI 스펙이 없습니다. 스펙 없는 API를 연결하는 전 과정을 실습합니다.

1) 설치

git clone https://github.com/automation-ai-labs/mcp-link.git
cd mcp-link
go mod download
go run main.go serve --port 8080 --host 0.0.0.0

Go 1.21 이상이 필요합니다. 설치 없이 바로 쓰려면 mcp-link.vercel.app 온라인 버전을 사용할 수 있습니다.

2) OpenAPI V3 스펙 준비

mcp-link는 s= 파라미터로 스펙 URL을 받습니다. 스펙이 이미 있다면 이 단계를 건너뛰고 3)으로 갑니다.

스펙이 없는 경우 — 세 가지 방법:

방법 A. 프레임워크 자동 생성 (자체 개발 API라면)

방법 B. AI로 스펙 작성 (외부 API, 문서만 있는 경우)

Claude에 아래처럼 요청합니다.

https://jsonplaceholder.typicode.com 의 REST API에 대한 OpenAPI V3 스펙을 작성해줘. /posts, /todos, /users 엔드포인트만 포함하고 YAML 형식으로 출력해줘.

생성된 스펙을 jsonplaceholder.yaml로 저장합니다.

openapi: "3.0.0"
info:
  title: JSONPlaceholder API
  version: "1.0.0"
servers:
  - url: https://jsonplaceholder.typicode.com
paths:
  /posts:
    get:
      summary: 모든 게시물 조회
      operationId: listPosts
      parameters:
        - name: userId
          in: query
          schema:
            type: integer
      responses:
        "200":
          description: 게시물 목록
  /posts/{id}:
    get:
      summary: 게시물 단건 조회
      operationId: getPost
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: 게시물
  /todos:
    get:
      summary: 할 일 목록 조회
      operationId: listTodos
      parameters:
        - name: userId
          in: query
          schema:
            type: integer
        - name: completed
          in: query
          schema:
            type: boolean
      responses:
        "200":
          description: 할 일 목록
  /users:
    get:
      summary: 사용자 목록 조회
      operationId: listUsers
      responses:
        "200":
          description: 사용자 목록
  /users/{id}:
    get:
      summary: 사용자 단건 조회
      operationId: getUser
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: 사용자

방법 C. 트래픽 캡처 (문서도 없고 코드도 없는 경우)

# Microsoft Dev Proxy 설치 후
devproxy --record
# API를 평소처럼 사용 후 중단
devproxy generate-openapi
# → openapi.json 자동 생성

스펙 파일을 URL로 올리기

mcp-link는 스펙을 URL로 읽습니다. gist.github.com에서 Gist를 만들고 "Raw" 버튼으로 URL을 얻습니다.

https://gist.githubusercontent.com/{user}/{id}/raw/jsonplaceholder.yaml

3) mcp-link 연결

JSONPlaceholder는 인증이 없으니 s=와 u=만 씁니다.

http://localhost:8080/sse?s={스펙_URL}&u=https://jsonplaceholder.typicode.com

인증이 필요한 API라면 h= 파라미터에 헤더를 추가합니다. Bearer 토큰의 공백은 %20으로 인코딩합니다.

http://localhost:8080/sse?s={스펙_URL}&u=https://api.example.com&h=Authorization:Bearer%20sk-xxxx

4) Claude Desktop에 등록

claude_desktop_config.json에 아래를 추가하고 Claude Desktop을 재시작합니다.

{
  "mcpServers": {
    "@jsonplaceholder": {
      "url": "http://localhost:8080/sse?s=https://gist.githubusercontent.com/{user}/{id}/raw/jsonplaceholder.yaml&u=https://jsonplaceholder.typicode.com"
    }
  }
}

5) 동작 확인

도구 목록에 listPosts, getPost, listTodos, listUsers, getUser가 등록됩니다. Claude에게 자연어로 질문합니다.

userId가 1인 사용자의 완료된 할 일만 보여줘

Claude가 listTodos 도구를 호출하면서 userId=1, completed=true 파라미터를 자동으로 채워 JSONPlaceholder API를 호출합니다.

<실행 화면 예시>

![[Pasted image 20260717084010.png]]

사용자 3번이 쓴 게시물 목록을 보여줘

이번엔 listPosts 도구에 userId=3을 넣어 호출합니다.

<실행 화면 예시>

![[Pasted image 20260717084141.png]]

5. MCP 서버 직접 구현 vs. mcp-link

한 줄 요약: 직접 구현은 커스텀 로직이 필요할 때. mcp-link는 "OpenAPI 스펙이 이미 있는 API"를 빠르게 연결할 때.

6. mcp-link vs. MCP 게이트웨이

mcp-link와 MCP 게이트웨이(Microsoft MCP Gateway, IBM ContextForge 등)는 자주 함께 언급되지만 역할이 다릅니다. 한 줄로 먼저 정리하면 이렇습니다.

mcp-link는 REST API를 MCP 서버로 만드는 도구, MCP 게이트웨이는 여러 MCP 서버를 관리하는 인프라.

계층으로 보기

[REST API A]──mcp-link──┐
[REST API B]──mcp-link──┤
[REST API C]──mcp-link──┼──▶ MCP 게이트웨이 ──▶ AI 에이전트
[커스텀 MCP 서버 D]──────┘

mcp-link는 각 REST API 앞에 붙어 MCP 서버를 만들어 줍니다. 게이트웨이는 그렇게 만들어진 MCP 서버 여러 개를 앞에서 받아 인증·라우팅·모니터링을 처리합니다.

기능 비교

언제 게이트웨이가 필요한가

mcp-link 단독으로 충분한 상황과 게이트웨이가 추가로 필요한 상황은 구분됩니다.

mcp-link만으로 충분한 경우
- 개인 개발 환경에서 단일 API를 빠르게 연결할 때
- 팀 내부에서 신뢰된 네트워크 안에서만 사용할 때
- PoC·프로토타입 단계에서 빠른 검증이 목적일 때

게이트웨이가 필요한 경우
- 여러 팀이 서로 다른 MCP 서버를 공유해서 쓸 때
- 에이전트별로 접근 가능한 도구를 제한해야 할 때
- 규정 준수·감사 로그가 요구될 때 (ISMS, SOC 2 등)
- mcp-link SSE 엔드포인트를 외부에 노출해야 할 때

자연스러운 도입 순서는 "mcp-link로 연결 → 규모가 커지면 게이트웨이 추가"입니다. 게이트웨이를 먼저 도입할 필요는 없고, mcp-link가 만든 MCP 서버를 그대로 게이트웨이 뒤에 놓으면 됩니다.

7. 한계: 타 도구 대비 상대적 제약

OpenAPI V3만 지원한다. V2(Swagger) 스펙은 변환되지 않습니다. 오래된 엔터프라이즈 API는 스펙을 먼저 업그레이드해야 합니다.

mcp-link 엔드포인트 자체에 인증이 없다. SSE URL(localhost:8080/sse)은 누구든 접근하면 도구를 호출할 수 있습니다. 로컬 개발 환경에서는 문제없지만, 팀이 공유하거나 서버에 올릴 때는 앞에 별도 인증 레이어가 필요합니다. 가장 간단한 방법은 Nginx/Caddy 같은 리버스 프록시에 Bearer 토큰 검증을 추가하는 것입니다. 감사 로그나 도구 단위 접근 제어가 필요한 경우는 6장을 참고하세요.

REST API 호출 시 OAuth 플로우를 지원하지 않는다. h= 파라미터는 정적 헤더만 지원합니다. OAuth 2.0을 사용하는 REST API는 토큰을 사전에 직접 발급해 고정값으로 넣어야 하고, 만료 시 URL을 수동으로 업데이트해야 합니다. mcp-link가 토큰 발급·갱신 흐름을 대신 처리하는 기능은 아직 없습니다. (mcp-link 서버 자체에 대한 접근 인증과는 별개의 문제입니다.)

응답 가공이 불가하다. 여러 API 응답을 조합하거나, 조건부 로직을 넣거나, 응답 형식을 바꾸는 것은 MCP 서버를 직접 만들어야 합니다.

일부 프레임워크와 호환성 문제. Langgraph MultiServerMCPClient, Spring AI에서 도구 이름 충돌 등 특정 프레임워크에서 이슈가 보고되고 있습니다(2025년 기준 오픈 이슈).

8. 마치며

REST API를 AI 에이전트에 연결하는 작업의 대부분은 OpenAPI 스펙에 이미 담긴 정보를 다른 포맷으로 옮기는 일입니다. mcp-link는 그 변환을 자동화합니다.

스펙이 없는 API도 AI로 스펙을 만드는 과정이 이제 수십 분이면 됩니다. mcp-link를 먼저 쓰고, 규모가 커지면 인프라를 추가하는 순서가 자연스럽습니다.

참조

• mcp-link GitHub
• mcp-link 온라인 데모
• JSONPlaceholder
• Model Context Protocol 공식 문서
• Generate an OpenAPI spec - Microsoft Dev Proxy
• Microsoft MCP Gateway
• IBM ContextForge
• awesome-mcp-gateways