내 서버를 클로드 도구로 — MCP HTTP 엔드포인트 하나로 데스크탑·모바일 동시에 쓰기

가족 여행 일정을 정리하는 앱이랑 우리 공동체 경비내역 앱을 만들어서 쓰고 있는데, 매번 앱을 열어서 항목을 하나씩 입력하는 게 은근히 귀찮았다. “여행 일정 등록해줘”, “이번 달 경비 얼마 썼는지 정리해줘”라고 말만 하면 클로드가 알아서 처리해주면 좋겠다 싶어서, 이 두 앱에 MCP 서버를 붙여봤다. 그런데 로컬 stdio 방식으로 만들면 맥에서만 쓸 수 있고 폰에서는 못 쓴다는 게 걸렸다. 그래서 HTTP 엔드포인트로 띄워서 데스크탑이랑 모바일에서 동시에 쓸 수 있게 만든 과정을 정리해본다.

왜 stdio가 아니라 HTTP인가

MCP 서버를 만드는 방법은 크게 두 가지다.

로컬 stdio 서버: 내 컴퓨터에서 프로세스로 실행되고, 클로드 데스크탑이 그 프로세스를 직접 띄워서 통신하는 방식. claude_desktop_config.json에 명령어를 등록해서 쓴다.
원격 HTTP 서버: 인터넷 어딘가에 떠 있는 서버고, 클로드가 URL로 접속해서 쓰는 방식.

문제는 stdio는 클로드 데스크탑이 내 컴퓨터에서 직접 프로세스를 실행해야 하니까 구조적으로 그 컴퓨터를 벗어날 수가 없다는 점이다. 반면 원격 커넥터는 Pro/Max/Team/Enterprise 플랜이면 클로드 웹, 데스크탑, 모바일(iOS/Android) 전부에서 동일하게 쓸 수 있다. 설정 한 번만 해두면 폰에서도 바로 쓸 수 있다는 뜻이라, 여행 앱이나 경비내역처럼 밖에서도 자주 쓰는 도구에는 HTTP 방식이 훨씬 맞았다.

서버는 뭘로 만들었나

이미 두 앱 다 Vercel에 올려둔 Next.js 프로젝트였어서, mcp-handler 패키지를 얹는 게 제일 간단했다. Next.js, Nuxt, SvelteKit 같은 프레임워크에 라우트 하나 추가하는 식으로 MCP 서버를 붙일 수 있게 해주는 어댑터다.

npm install mcp-handler @modelcontextprotocol/sdk zod

그리고 app/api/mcp/route.ts 같은 파일을 하나 만들어서 도구(tool)를 등록한다.

import { createMcpHandler } from "mcp-handler";
import { z } from "zod";

const handler = createMcpHandler((server) => {
  server.tool(
    "add_trip_item",
    "여행 일정에 항목을 추가한다",
    { tripId: z.number(), title: z.string(), date: z.string() },
    async ({ tripId, title, date }) => {
      // DB에 일정 저장하는 로직
      return { content: [{ type: "text", text: "일정이 등록됐다" }] };
    }
  );
});

export { handler as GET, handler as POST };

각 도구마다 이름, 설명, 입력 스키마(zod), 실제 실행 로직만 정의해주면 된다. 여행 앱에는 일정 추가/조회/수정, 경비내역 앱에는 거래 추가/조회/카테고리 목록 같은 도구를 이런 식으로 하나씩 붙였다.

이 작업 자체를 클로드 코드로 시켰다

사실 위 라우트 파일이랑 도구 정의를 하나하나 손으로 짠 건 아니고, 클로드 코드한테 시켰다. 기존 프로젝트 폴더에서 클로드 코드를 실행해두면 DB 스키마나 기존 API 코드를 알아서 읽어보고, 그에 맞는 MCP 도구를 만들어준다.

실제로 이런 식으로 프롬프트를 던졌다.

이 프로젝트에 mcp-handler를 붙여서 MCP 서버를 만들어줘.
기존 trips, trip_items 테이블 구조를 참고해서
일정 추가/조회/수정/삭제 도구를 각각 만들고,
app/api/mcp/route.ts에 등록해줘.

클로드 코드는 기존 스키마와 API 라우트를 스캔해서 관련 타입을 그대로 재사용하고, 도구 설명도 한글로 적당히 붙여준다. 사람이 손으로 짤 때보다 확실히 빠르고, 특히 기존 코드베이스가 이미 있는 프로젝트에 MCP를 “얹는” 작업에는 잘 맞았다. 물론 생성된 코드는 한 번씩 훑어보고, 도구 이름이나 설명이 애매하면 손으로 다듬는 과정은 거쳤다.

배포하고 URL 확인하기

Vercel에 올려둔 프로젝트라 git push 한 번이면 배포가 끝난다. 배포 후에는 https://내도메인/api/mcp 같은 주소가 MCP 엔드포인트가 된다.

인증은 처음엔 OAuth까지 붙이기 번거로워서, URL 경로에 긴 랜덤 토큰을 하나 심어두는 방식으로 간단하게 처리했다. 개인용으로 나 혼자 쓰는 도구라면 이 정도로도 충분하다. 여러 사람이 같이 쓰거나 공개할 도구라면 OAuth 인증을 붙이는 게 맞다.

클로드에 커넥터로 등록하기

서버가 준비되면 클로드 쪽 설정은 정말 간단하다.

클로드(웹 또는 데스크탑)에서 설정 → 커넥터로 이동
커스텀 커넥터 추가 클릭
이름과 방금 만든 엔드포인트 URL 입력
저장

여기서 핵심은, 이 설정이 계정 단위로 저장된다는 점이다. 데스크탑에서 한 번 등록해두면 모바일 앱에서도 로그인만 되어 있으면 똑같이 나타난다. 기기마다 따로 설정할 필요가 없다.

실제로 써보니

폰으로 “가족 여행에 3일차 일정 하나 추가해줘”라고 말하면 바로 서버에 데이터가 들어가고, 맥 앞에서 “이번 달 경비 카테고리별로 정리해줘”라고 하면 등록해둔 도구가 그대로 호출된다. 앱을 열 필요 없이 대화만으로 처리되니까 체감 편의성이 꽤 크다.

다만 몇 가지 주의할 점은 있었다.

원격 MCP는 유료 플랜(Pro 이상)에서만 쓸 수 있다
아직 베타 기능이라 가끔 도구 목록을 못 불러오는 경우가 있는데, 커넥터를 껐다 켜면 대부분 해결된다
민감한 개인 데이터라면 URL 토큰만으로는 부족할 수 있으니 접근 범위를 최소한으로 설계하는 게 좋다

정리

stdio는 로컬 전용, HTTP 원격 서버는 데스크탑+모바일 동시 사용 가능
Next.js 프로젝트라면 mcp-handler 패키지로 라우트 하나 추가하는 정도로 서버 구축 가능
클로드 설정 → 커넥터에 URL 한 번 등록하면 계정에 연결되어 기기 구분 없이 동작
개인용 도구는 URL 토큰 방식으로도 충분하지만, 공유용이라면 OAuth 인증을 고려할 것

이미 만들어둔 개인 웹앱이 있다면, MCP 서버 하나 얹는 것만으로 “말로 시키는 도구”가 되는 셈이라 생각보다 활용도가 높다. 🙂