MCP 서버(SSE URL) 사용 방법

모델 컨텍스트 프로토콜(MCP) 서버는 특수 서버를 통해 향상된 AI 기능을 제공하는 Cursor의 강력한 기능입니다. 이 가이드는 Cursor의 기능을 확장하기 위해 서버 전송 이벤트(SSE) URL을 사용하여 MCP 서버를 이해하고 활용하는 방법을 안내합니다.

MCP 서버와 SSE 소개

MCP(모델 컨텍스트 프로토콜) 서버는 Cursor와 다양한 AI 모델 또는 서비스 사이의 특수 미들웨어 역할을 합니다. 이들은 Cursor의 AI 기능을 향상시키는 추가 컨텍스트, 도구 및 기능을 제공합니다. 서버 전송 이벤트(SSE)는 서버가 HTTP 연결을 통해 클라이언트에 업데이트를 푸시할 수 있게 하여 실시간 통신을 가능하게 하는 기술입니다.

MCP 서버란?

MCP 서버는 모델 컨텍스트 프로토콜을 구현하는 특수 서버로, Cursor가 다음을 수행할 수 있게 합니다:

• 추가 도구와 리소스 액세스
• 외부 API와 서비스에 연결
• AI 모델로 보내기 전에 데이터 처리 및 변환
• 사용자 정의 기능으로 Cursor의 기능 확장

SSE URL을 사용하는 이유?

SSE(서버 전송 이벤트) URL은 Cursor와 MCP 서버 간의 연결을 설정하는 표준화된 방법을 제공하며 다음과 같은 이점이 있습니다:

• 실시간 업데이트와 스트리밍 응답
• 서버에서 클라이언트로의 효율적인 단방향 통신
• 자동 재연결 처리
• 표준 HTTP 인프라와의 호환성

SSE URL 구조 이해하기

MCP 서버의 SSE URL은 일반적으로 다음 구조를 따릅니다:

http(s)://<hostname>:<port>/sse?token=<auth_token>

구성 요소 설명:

• 프로토콜: http:// 또는 https://(보안, 권장)
• 호스트명: 서버 주소(예: localhost, mcp.example.com)
• 포트: MCP 서버가 수신 대기하는 포트 번호(예: 3000)
• 경로: 일반적으로 서버 전송 이벤트 엔드포인트의 경우 /sse
• 토큰: 보안 액세스를 위한 인증 토큰

구성 단계

SSE URL을 사용하여 MCP 서버를 설정하고 사용하는 것은 여러 단계를 포함합니다:

1. 필요한 종속성 설치

먼저 필요한 종속성이 설치되어 있는지 확인하세요:

npm install @modelcontextprotocol/sdk

2. MCP 서버 구성 생성

MCP 서버의 구성 파일을 생성합니다. 이는 Cursor의 구성 디렉토리에 배치할 수 있습니다:

{
  "mcpServers": {
    "example-server": {
      "command": "node",
      "args": ["/path/to/your/mcp-server.js"],
      "env": {
        "API_KEY": "your-api-key-here",
        "OTHER_ENV_VAR": "value"
      },
      "disabled": false,
      "autoApprove": ["tool1", "tool2"]
    }
  }
}

3. SSE 연결 설정

MCP 서버 구현에서 SSE 엔드포인트를 설정합니다:

import express from 'express';
import cors from 'cors';

const app = express();
app.use(cors());

app.get('/sse', (req, res) => {
  // 토큰 검증
  const token = req.query.token;
  if (!validateToken(token)) {
    return res.status(401).send('Unauthorized');
  }

  // SSE를 위한 헤더 설정
  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');
  res.setHeader('Connection', 'keep-alive');

  // 초기 연결 메시지 전송
  res.write('event: connected\ndata: {"status": "connected"}\n\n');

  // 클라이언트 연결 해제 처리
  req.on('close', () => {
    console.log('Client disconnected');
  });

  // 주기적 메시지 또는 이벤트에 대한 응답 설정
  // ...
});

app.listen(3000, () => {
  console.log('MCP Server listening on port 3000');
});

4. Cursor에서 MCP 서버 사용 구성

Cursor의 설정에 MCP 서버 구성을 추가합니다:

1. Cursor 실행
2. 설정(⚙️)으로 이동
3. "MCP" 검색
4. 서버 구성 추가
5. 변경 사항 저장

사용 예시

다음은 SSE URL을 사용하는 MCP 서버의 실제 예시입니다:

예시 1: 기본 도구 구현

// MCP 서버 구현에서
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: 'weather_lookup',
      description: '위치의 현재 날씨 조회',
      inputSchema: {
        type: 'object',
        properties: {
          location: {
            type: 'string',
            description: '도시 이름 또는 우편번호'
          }
        },
        required: ['location']
      }
    }
  ]
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === 'weather_lookup') {
    const location = request.params.arguments.location;
    const weatherData = await fetchWeatherData(location);
    
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(weatherData, null, 2)
        }
      ]
    };
  }
});

예시 2: 리소스 구현

server.setRequestHandler(ListResourcesRequestSchema, async () => ({
  resources: [
    {
      uri: 'docs://api/reference',
      name: 'API 참조 문서',
      mimeType: 'text/markdown',
      description: '프로젝트의 전체 API 참조'
    }
  ]
}));

server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
  if (request.params.uri === 'docs://api/reference') {
    return {
      contents: [
        {
          uri: request.params.uri,
          mimeType: 'text/markdown',
          text: await fs.readFile('path/to/api-docs.md', 'utf-8')
        }
      ]
    };
  }
});

일반적인 문제 해결

연결 거부

문제: Cursor가 MCP 서버에 연결할 수 없습니다.

해결책:

• 서버가 실행 중인지 확인
• 방화벽 설정 확인
• 포트가 올바르고 접근 가능한지 확인
• 호스트명이 올바르게 해석되는지 확인

인증 실패

문제: 연결 시 "Unauthorized" 오류가 발생합니다.

해결책:

• 토큰이 올바르게 구성되었는지 확인
• 토큰 검증 로직 확인
• 환경 변수가 올바르게 설정되었는지 확인

서버 충돌

문제: MCP 서버가 예기치 않게 충돌합니다.

해결책:

• 적절한 오류 처리 구현
• 문제 식별을 위한 로깅 추가
• 메모리 누수 확인
• 처리 전 입력 데이터 검증

느린 응답

문제: MCP 서버 응답이 느립니다.

해결책:

• 서버 코드 최적화
• 적절한 캐싱 구현
• 리소스 확장 고려
• 차단 작업 확인

모범 사례

보안

• 프로덕션 MCP 서버에는 항상 HTTPS 사용
• 적절한 인증 및 권한 부여 구현
• 주입 공격 방지를 위한 모든 입력 검증
• 필요한 기능만 노출하도록 제한

성능

• 자주 액세스하는 리소스에 대한 캐싱 구현
• 효율적인 데이터 구조와 알고리즘 사용
• 대용량 데이터에 대한 스트리밍 응답 고려
• 서버 성능 모니터링 및 병목 현상 최적화

신뢰성

• 적절한 오류 처리 구현
• 디버깅을 위한 로깅 추가
• 상태 확인 설정
• 충돌한 서버의 자동 재시작 구현

개발 워크플로우

• 테스트를 위한 로컬 개발 환경 사용
• MCP 서버의 버전 관리 구현
• 서버의 기능과 요구 사항 문서화
• 서버 기능에 대한 자동화된 테스트 생성

결론

SSE URL을 사용하는 MCP 서버는 사용자 정의 기능과 외부 서비스로 Cursor의 기능을 확장하는 강력한 방법을 제공합니다. 이 가이드에 설명된 구성 단계와 모범 사례를 따르면 개발 워크플로우를 향상시키는 강력하고 안전하며 효율적인 MCP 서버를 만들 수 있습니다.

외부 API에 연결하든, 사용자 정의 도구를 구현하든, AI 모델에 추가 컨텍스트를 제공하든, MCP 서버는 Cursor의 기능을 확장하는 유연하고 표준화된 접근 방식을 제공합니다.

추가 리소스

• 공식 MCP SDK 문서
• MDN의 서버 전송 이벤트 문서
• Cursor 문서
• Express.js 문서