AI 어시스턴트를 위한 MCP 서버

Model Context Protocol로 Claude Code, Claude Desktop, Cursor를 워크스페이스에 연결합니다. 바로 쓰는 설정과 도구 목록, 권한, 요금제 제한을 다룹니다.

2026년 8월 14일 업데이트

MCP 서버를 쓰면 AI 어시스턴트가 여러분의 링크와 분석 데이터를 직접 다룰 수 있습니다. “이 랜딩 페이지를 우리 브랜드 도메인으로 단축해 줘”, “지난주에 클릭이 가장 많았던 링크 다섯 개는 뭐야”, “캠페인 도메인의 알림 규칙을 월요일까지 꺼 둬” 같은 식입니다. 어시스턴트는 여러분이 직접 호출할 때와 똑같은 공개 API를 거쳐 이 일을 하며, 권한은 연결에 쓴 키가 가진 그대로입니다.

https://api.linkprofit.com/v1/mcp

전송 방식은 HTTP 위의 JSON-RPC 2.0이며 Model Context Protocol의 2025-06-18 리비전을 따릅니다(2025-03-26 리비전도 받아들입니다). 서버가 먼저 여는 이벤트 스트림도, 세션 상태도 없습니다. GET과 DELETE는 405로 응답하고, Mcp-Session-Id는 발급되지 않으며, 모든 요청은 필요한 맥락을 키 자체에 담아 옵니다. HTTP를 말하는 MCP 클라이언트라면 무엇이든 동작합니다. 아래 세 가지는 그저 복사해 붙이는 설정을 함께 제공하는 것들일 뿐입니다.

1. 어시스턴트용 키 만들기

대시보드에서 설정 → API 키를 열고 워크스페이스 키(lp_live_…)를 만드십시오. 어시스턴트에게 정말 필요한 스코프만 부여하십시오. 각 도구에 무엇이 필요한지는 아래 도구 목록에 정리되어 있습니다. links:read + analytics:read만 가진 키는 질문에는 답하되 아무것도 바꾸지 못하는 읽기 전용 어시스턴트를 만들어 줍니다.

키의 전체 값은 한 번만 표시됩니다. 비밀번호처럼 다루십시오. 이 값은 여러분의 컴퓨터에 있는 설정 파일로 들어갑니다.

2. 클라이언트에 서버 추가하기

Claude Code

명령 한 줄이면 되고, 설정 파일을 고칠 필요도 없습니다.

claude mcp add --transport http linkprofit https://api.linkprofit.com/v1/mcp \
  --header "Authorization: Bearer lp_live_…your key…"

--scope user를 덧붙이면 현재 프로젝트뿐 아니라 컴퓨터의 모든 프로젝트에서 이 서버를 쓸 수 있습니다. 결과는 claude mcp list로 확인하고, 나중에 지울 때는 claude mcp remove linkprofit을 사용하십시오.

Claude Desktop

설정 파일을 열어 서버를 추가하십시오. macOS에서는 ~/Library/Application Support/Claude/claude_desktop_config.json, Windows에서는 %APPDATA%\Claude\claude_desktop_config.json입니다.

{
  "mcpServers": {
    "linkprofit": {
      "type": "http",
      "url": "https://api.linkprofit.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer lp_live_…your key…"
      }
    }
  }
}

Claude Desktop을 다시 시작하십시오. 새 대화의 도구 선택기에 도구들이 나타납니다.

Cursor

프로젝트에 .cursor/mcp.json을 만드십시오(어디에서나 쓰려면 ~/.cursor/mcp.json입니다).

{
  "mcpServers": {
    "linkprofit": {
      "url": "https://api.linkprofit.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer lp_live_…your key…"
      }
    }
  }
}

Cursor는 저장하는 즉시 파일을 읽어 들이고 Settings → MCP에 서버를 표시합니다.

연결을 직접 확인하기

어떤 클라이언트든 문제는 프로토콜 수준에서 보는 편이 훨씬 읽기 쉽습니다. 아래는 클라이언트들이 수행하는 것과 같은 핸드셰이크입니다.

curl -s -X POST https://api.linkprofit.com/v1/mcp \
  -H "Authorization: Bearer $LINKPROFIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "curl", "version": "1.0" }
    }
  }'

정상 응답에는 프로토콜 버전과 서버, 그리고 도구 기능이 담깁니다. 메서드를 tools/list로 바꾸면 도구 목록을 볼 수 있고, ping으로 바꾸면 연결이 되는지만 확인할 수 있습니다.

도구

도구는 열 개이며 모두 키가 속한 워크스페이스 안에서만 동작합니다. 스코프 열은 키가 갖춰야 하는 스코프입니다. 키에 스코프가 없는 도구는 목록에서 감춰지는 것이 아니라 호출할 때 실패합니다.

| 도구 | 하는 일 | 필요한 스코프 | | --- | --- | --- | | list_links | 워크스페이스의 단축 링크 목록을 보여 주며, 검색어로 걸러낼 수도 있습니다 | links:read | | get_link | id로 링크 하나를 조회합니다 | links:read | | create_link | 단축 링크를 만듭니다. domain_id가 없으면 워크스페이스의 기본 도메인을 사용합니다 | links:write | | update_link | 기존 링크의 도착 주소나 제목을 바꿉니다 | links:write | | analytics_summary | 기간별 클릭과 방문자, QR 스캔 수이며 링크 하나만 볼 수도 있습니다 | analytics:read | | analytics_breakdown | 국가, 도시, 기기, 브라우저, OS, 리퍼러, UTM별로 묶은 클릭과 방문자 | analytics:read | | analytics_top_links | 해당 기간에 클릭이 가장 많았던 링크와 그 클릭 수, 방문자 수 | analytics:read | | analytics_timeseries | 시간, 일, 주 단위로 본 클릭과 방문자의 추이 | analytics:read | | list_alert_rules | 알림 규칙과 그 채널, 재알림 방지 간격을 보여 줍니다 | alerts:read | | update_alert_rule | 알림 규칙을 켜거나 끄고, 재알림 방지 간격을 다시 조정합니다 | alerts:write |

인자 스키마는 호출을 검증하는 것과 같은 정의에서 나옵니다. 그래서 어시스턴트가 도구에 대해 전해 듣는 내용과 서버가 실제로 받아들이는 내용이 서로 어긋날 수 없습니다. 읽기 전용 도구에는 그렇다는 표시가 붙어 있고, 그 덕분에 클라이언트는 데이터를 바꾸는 세 가지 도구, 즉 create_link와 update_link, update_alert_rule 그리고 앞으로 그 목록에 더해질 도구를 실행하기 전에 확인을 요청할 수 있습니다.

데이터를 변경하는 도구 호출은 모두 워크스페이스 감사 로그에 기록되며, 어떤 키가 호출했는지와 MCP를 통해 들어왔다는 사실이 함께 남습니다. 그래서 어시스턴트가 만든 변경도 사람이 만든 변경만큼 추적할 수 있습니다.

권한과 안전

권한의 경계는 키입니다. 특별대우를 받는 “어시스턴트 모드” 같은 것은 없습니다. 도구 호출은 키가 가진 스코프로, 키가 속한 워크스페이스 안에서, REST 호출과 똑같은 요청 제한과 똑같은 테넌트 격리 아래 실행됩니다. 다른 워크스페이스의 id는 REST에서와 똑같이 not_found입니다.

몸에 익혀 둘 만한 습관이 셋 있습니다.

어시스턴트에게는 전용 키를 주십시오. 운영 연동이 쓰는 키를 그대로 주어서는 안 됩니다. 그러면 폐기해도 잃을 것이 없습니다.
읽기 전용으로 시작하십시오. 사람들이 실제로 어시스턴트에게 던지는 리포팅 질문은 links:read + analytics:read로 모두 답할 수 있습니다. links:write는 대화창에서 링크를 만들고 싶어졌을 때 그때 추가하십시오.
노출되면 교체하십시오. 설정 파일에 든 키는 백업과 화면 공유, 지원 티켓을 타고 함께 돌아다닙니다. 새어 나간 순간 대시보드에서 폐기하십시오. 다음 요청부터 401이 반환됩니다.

요청 제한은 REST API와 공유합니다. 키별로 1분 슬라이딩 윈도를 쓰므로, 말 많은 어시스턴트와 백그라운드 작업이 같은 키를 쓰면 같은 예산을 두고 다투게 됩니다. 키를 따로 두어야 할 이유가 하나 더 생기는 셈입니다. 헤더와 재시도 규칙은 요청 제한을 참고하십시오.

요금제 요건

이 엔드포인트는 요금제 기능 두 가지가 통제합니다.

api_access — API를 쓸 수 있는 권한 자체입니다.
assistant_tools — 도구 목록을, 따라서 MCP를 쓸 수 있는 권한입니다.

둘 다 워크스페이스가 쓰고 있는 요금제에서 정해집니다. 요금제에 둘 중 하나라도 빠져 있으면 plan_restricted 코드와 함께 403이 반환되고, 메시지에 빠진 기능의 이름이 담깁니다. LinkProfit을 여러분의 브랜드로 재판매한다면, 이 기능을 요금제에 포함할지 상위 요금제로 팔지는 여러분이 정합니다.

문제 해결

403 plan_restricted — 요금제에 assistant_tools(또는 api_access)가 포함되어 있지 않습니다. 요금제를 상향하십시오. 이 문제만큼은 키나 클라이언트 설정을 아무리 손봐도 해결되지 않습니다.

401 unauthorized — 헤더가 없거나 형식이 잘못되었거나, 키를 알 수 없거나 폐기되었거나 만료되었습니다. 이 셋은 일부러 구분되지 않게 되어 있습니다. 값이 키 전체가 맞는지, 앞에 Bearer 가 붙어 있는지, 클라이언트가 헤더를 정말로 보내고 있는지 확인하십시오. 위의 curl 핸드셰이크가 요청 한 번으로 답을 줍니다.

403 forbidden — 파트너 키(lpp_live_…)를 썼습니다. MCP는 워크스페이스용 기능이므로 워크스페이스 키를 만드십시오.

429 rate_limited — 키가 윈도 용량을 다 썼습니다. 응답에는 Retry-After가 담겨 있습니다. 곧바로 재시도하는 클라이언트는 키를 계속 잠긴 상태로 둘 뿐입니다.

GET 요청에 대한 405 — 고장이 아니라 예정된 동작입니다. 서버는 이벤트 스트림을 제공하지 않고 세션도 유지하지 않습니다. 예전 리비전의 SSE 기반 전송만 말할 수 있는 클라이언트는 연결할 수 없습니다.

도구가 데이터 대신 오류로 답합니다 — 대화 기록에서는 서로 다른 두 가지가 비슷해 보입니다. 검증을 통과하지 못한 인자는 오류로 표시된 도구 결과로 돌아오며 문제가 된 필드가 함께 나열되므로, 어시스턴트가 스스로 고쳐서 다시 시도할 수 있습니다. 스코프가 없는 경우에는 insufficient_scope 코드와 빠진 스코프 이름이 담긴 프로토콜 오류가 돌아옵니다. 이쪽은 다시 시도할 일이 아니라 새 키가 필요합니다.

함께 읽기

인증 방식 — 키와 전체 스코프 목록, 키 교체.
오류 처리 — 모든 오류 코드와 각각의 처리 방법.
API 레퍼런스 — 도구 뒤에 있는 REST 엔드포인트.
클라이언트 라이브러리 — 같은 작업을 여러분의 코드에서 수행합니다.