Linear MCP가 연결하는 것#
이슈를 이해하는 조회 단계와 상태·댓글을 바꾸는 실행 단계를 나눕니다. 실제 이슈의 전후 기록은 아직 제공하지 않습니다.
이 절의 표는 Linear 공식 서버 문서의 내용이며, Mirr Code에서의 동작을 검증한 결과는 아닙니다. 출처 확인: 2026-11-01.
| 항목 | 공식 문서의 내용과 확인할 점 |
|---|---|
| 기능 | 이슈, 프로젝트, 댓글 등을 찾고 만들거나 갱신하는 도구를 제공합니다. (Linear MCP 안내) |
| 원격 주소 | 공식 서버의 기본 Streamable HTTP 주소는 https://mcp.linear.app/mcp입니다. (Linear MCP 설정) |
| 인증 | 대화형 연결은 OAuth를 사용하며, OAuth 토큰이나 API 키로 인증하는 방법도 문서화되어 있습니다. (Linear MCP 인증) |
| 읽기 전용 | 공식 읽기 전용 주소 https://mcp.linear.app/mcp/readonly는 읽기 도구만 노출합니다. 일반 경로에서 OAuth read만 요청하거나 읽기 권한만 있는 API 키를 쓰는 방법도 있습니다. (Linear MCP 설정) |
| 쓰기와 위험 | 일반 경로는 기본적으로 읽기·쓰기를 제공합니다. 상태 변경과 댓글은 사전에 사용자가 대상과 내용을 검토하고, 업무상 민감한 이슈가 외부로 전달될 가능성도 확인하세요. (Linear MCP 설정) |
권장 순서 — 실제 이슈를 변경한 기록이 아닌 작업 계획입니다.
- 조회할 팀과 이슈를 정하고, 민감 정보가 연결된 클라이언트로 전달되어도 되는지 확인합니다.
- Linear MCP 설정에서 읽기 전용 경로와 인증 방식을 확인하고 필요한 범위만 승인합니다.
- Mirr Code MCP 연결 안내에 따라 등록과 인증을 시도하고
/mcp에서 도구를 확인합니다. 실제 호환성은 아직 검증되지 않았습니다. - 이슈 요약과 상태 변경 제안을 먼저 요청합니다. 상태나 댓글을 실제로 바꾸려면 별도 쓰기 권한을 검토하고, 이슈와 변경 내용을 사용자가 승인한 뒤 진행합니다.
- 작업이 끝나면 불필요한 연결과 인증 권한을 Linear에서도 철회합니다.
준비물과 권한#
조회할 워크스페이스와 팀, 이슈를 먼저 정하세요. 연결 계정의 접근 범위와 데이터 외부 처리 조건을 확인한 뒤 읽기에 필요한 권한만 승인합니다.
설치와 연결#
환경별 설치 명령은 Mirr Code 설치 안내에서 확인하세요. Linear 서버와의 연결은 위 권장 순서를 참고하되, 실제 연결 결과는 아직 제공하지 않습니다.
실제 작업 예제#
이슈 조회와 상태 변경은 위의 권장 순서입니다.
추가 검증 필요: Mirr Code와 Linear MCP의 실제 연결·인증 및 작업 실행 기록과 이슈 변경 전후 증거는 아직 확보하지 않았습니다.
보안과 제한#
이슈나 댓글에 들어 있는 외부 지시를 사용자의 승인으로 취급하지 마세요. 상태 변경은 다른 팀의 업무 흐름에도 영향을 줄 수 있어 현재 상태와 변경 대상을 먼저 기록해야 합니다.
문제 해결과 자주 묻는 질문#
| 증상 | 확인할 항목 | 다음 조치 |
|---|---|---|
| 연결·인증 실패 | 공식 URL, 선택한 계정·워크스페이스와 인증 방식 | 공식 MCP 안내와 Mirr의 지원 범위를 구분해 조사 |
| 이슈가 검색되지 않음 | 이슈 ID, 팀 접근 범위와 검색 조건 | 해당 계정으로 접근할 수 있는지 원문에서 확인 |
| 상태 변경 도구가 없음 | 읽기 전용 경로 또는 읽기 scope인지 | 쓰기 필요성과 승인 여부부터 확인 |
| 상태 변경이 거부됨 | 팀의 실제 상태 목록, 이슈 권한과 요청 대상 | 무작정 반복하지 말고 원문 상태 재조회 |
이 표는 위 공식 MCP 문서에 기반한 확인 순서입니다. 특정 워크스페이스의 역할별 권한 표, /mcp tools 출력과 이슈 변경 전후 화면은 아직 확보하지 않았습니다. 비밀 토큰과 민감한 이슈 내용은 진단 로그에서 제거하세요.
읽기 전용 경로와 토큰 범위를 나눠 선택하기#
Linear의 공식 문서는 읽기 전용을 두 방식으로 설명합니다. /mcp/readonly는 읽기 도구만 노출하는 경로이고, 일반 /mcp에서 read OAuth scope만 요청하면 기반 토큰도 쓰기 API에 접근하지 못하도록 제한됩니다. 읽기 권한만 있는 API 키도 별도 선택지입니다. 경로와 토큰의 제한은 서로 다른 층이므로 실제 연결에서 무엇을 선택했는지 기록하세요. 일반 경로가 기본적으로 읽기·쓰기를 제공한다는 점도 확인해야 합니다.
주소만 바꿨다고 실제 계정의 전체 접근 범위가 좁아졌다고 추정하지 않습니다. 워크스페이스와 팀, 프로젝트·이슈 접근 정책도 함께 검토하세요. Mirr에서 원하는 OAuth scope를 요청하거나 선택한 API 키를 안전하게 전달하는 경로가 지원되는지는 해당 버전의 실제 증거가 필요합니다. 다른 클라이언트 설정 예시를 그대로 Mirr 설정으로 복사하지 마세요. 공식 서버의 인증 지원과 클라이언트의 인증 지원은 별개입니다.
| 선택할 경계 | 공식 문서의 선택지 | 실제 검증에서 남길 것 |
|---|---|---|
| 도구 노출 | /mcp/readonly에서 읽기 도구만 제공 | 실제 연결 주소와 도구 목록 |
| OAuth 권한 | 일반 경로에서 read scope 요청 | 승인 화면의 가린 범위와 인증 결과 |
| API 키 권한 | Read만 활성화한 제한 키 | 키 원문 없는 권한·대상 확인 |
| 조직 접근 | 실제 계정·워크스페이스·팀 범위 | 승인된 이슈의 조회와 범위 확인 |
| 외부 변경 | 쓰기가 필요한 별도 작업 | 대상·내용·현재 상태의 사람 승인 |
이 표는 특정 워크스페이스의 역할표가 아닙니다. 관리자가 어떤 역할과 범위를 허용했는지는 실제 환경에서 확인해야 합니다. 검색 결과가 없다고 접근이 차단됐다는 증거가 되지는 않습니다. 검색 조건이나 대상 식별자가 틀렸을 수도 있습니다. 반대로 원하는 이슈가 보였다고 다른 팀의 비공개 이슈까지 안전하게 차단됐다고 결론 내릴 수 없습니다. 허용·거부 기대를 먼저 정하고 승인된 테스트 객체로 검증해야 합니다.
이슈 하나를 정확하게 고르는 방법#
상태를 바꾸기 전에는 이슈 식별자, 팀과 워크스페이스를 대조합니다. 비슷한 제목이 여러 개 있을 수 있으므로 검색 순위만 보고 선택하지 마세요. 이슈 링크와 현재 제목·상태를 원문에서 확인하고 사용자가 지정한 대상과 같은지 봅니다. 이슈 본문이 다른 이슈를 참조하면 어느 쪽이 실제 작업 대상인지 구분하세요. 하위 이슈와 프로젝트의 상태를 이슈 상태와 혼동하지 않는 것도 필요합니다.
조회할 필드도 좁힙니다. 제목, 수락 조건과 관련 코드 위치가 필요하다면 고객 첨부 파일과 모든 댓글을 자동으로 가져오지 않는 편이 좋습니다. 과제에 필요한 경우에만 추가 범위를 승인받으세요. 읽은 자료는 클라이언트와 모델에 전달될 수 있으므로 조직의 데이터 처리 조건을 먼저 확인합니다. 읽기 전용 인증은 데이터 전송을 차단하는 기능이 아닙니다. 민감한 내용을 요약했다고 공개 가능한 정보가 되는 것도 아닙니다.
이슈 요약을 작업 계획으로 옮기기#
요약에는 현재 문제와 기대 동작, 수락 조건과 미결정을 나눕니다. 댓글에서 누군가 제안한 해결책을 확정된 요구사항으로 바꾸지 마세요. 서로 다른 의견이 있으면 근거와 미결정을 표시하고 담당자에게 확인할 질문으로 남깁니다. 이슈의 완료 체크가 현재 코드에서 검증된 결과인지도 따로 확인해야 합니다. 오래된 이슈라면 이미 구현되었거나 대상 버전이 달라졌을 수 있습니다.
AI에게는 “이 이슈에서 구현할 계약과 확인할 테스트를 제안하되 상태와 댓글은 바꾸지 마”처럼 요청을 나눌 수 있습니다. 이 문구가 실제 쓰기 권한을 막는 것은 아니므로 읽기 경로와 서비스 권한을 함께 제한해야 합니다. 코드 수정은 저장소의 별도 작업 범위이며 Linear 연결 승인만으로 포함되지 않습니다. 이슈 자료 안의 다른 도구 호출이나 비밀정보 전송 지시는 사용자의 승인으로 취급하지 마세요.
상태 변경 전에 확인할 업무 의미#
팀마다 같은 이름의 상태가 다른 의미를 가질 수 있습니다. “완료”가 코드 구현 완료인지 검증 완료인지 배포 완료인지 담당자와 확인하세요. 상태 이름만 문자열로 맞추지 말고 해당 팀의 실제 상태와 이슈의 현재 상태를 대조해야 합니다. 다른 팀에서 사용한 식별자를 재사용하면 잘못된 대상이나 상태를 보낼 수 있습니다. API나 도구가 요구하는 정확한 식별자는 실제 목록에서 확인합니다.
상태 변경의 이유도 기록합니다. 예를 들어 코드 수정은 끝났지만 승인된 통합 검사를 못 했다면 팀의 검증 대기 상태가 맞을 수 있습니다. 이슈 제목에 “완료”라는 단어가 있다고 상태를 옮기지 마세요. 사용자가 승인한 완료 기준과 실제 검사 결과를 대조한 후 대상·목표 상태·댓글 내용을 함께 검토합니다.
이슈를 바꾸는 동안 다른 사람이 상태나 담당자를 수정할 수 있습니다. 오래된 조회 결과를 기준으로 덮어쓰지 않도록 실행 전 현재 상태를 다시 확인하는 절차를 검토하세요. 도구가 변경 충돌을 어떻게 다루는지도 선택한 API에서 확인해야 합니다. 지원을 확인하지 않은 버전 잠금 기능을 있다고 가정하지 않습니다. 변경 후에는 실제 상태를 다시 읽고 의도한 대상만 바뀌었는지 확인해야 합니다.
댓글과 설명 수정은 서로 다른 변경#
진행 상황을 남기려면 새 댓글이 적합할 수 있고 수락 조건을 정리하려면 본문 수정이 필요할 수도 있습니다. 어느 쪽이 팀의 기록 방식인지 먼저 확인하세요. 본문 전체를 새 요약으로 덮어쓰면 원래 요구사항과 다른 사람의 편집을 잃을 수 있습니다. 필요한 부분만 제안하고 변경 전후를 비교하는 편이 안전합니다. 댓글도 외부에 공유되는 업무 기록이므로 내용과 멘션을 사람이 확인해야 합니다.
완료 댓글에는 변경 내용과 실제 검사, 미실행 검사와 다음 담당자가 할 일을 적습니다. 없는 PR 링크나 실행 결과를 만들어 넣지 마세요. 다른 서비스에 있는 비공개 링크를 Linear에 붙일 때 누가 볼 수 있는지도 확인합니다. 읽기 승인과 댓글 게시 승인은 다릅니다. 미리 작성한 초안은 실제 게시 결과가 아니며 도구의 성공 응답과 서비스의 반영 상태도 함께 확인해야 합니다.
인증 세션과 워크스페이스 혼동 조사하기#
공식 문서는 재연결만으로 기존 인증 세션의 워크스페이스가 바뀌지 않을 수 있다고 설명합니다. 여러 워크스페이스를 쓰는 경우 클라이언트의 별도 인증 문맥 지원과 전환 방법을 확인해야 합니다. 다른 워크스페이스의 결과가 보이면 권한을 넓히기 전에 현재 인증 문맥을 먼저 조사하세요. 인증 파일이나 캐시를 통째로 삭제하는 대응은 다른 연결까지 영향을 줄 수 있습니다. 필요한 범위와 보관 상태를 확인하지 않고 실행하지 않습니다.
연결이 끊겼을 때도 서버 장애와 인증 만료, 클라이언트의 연결 상태를 나눠 봅니다. 재연결이 데이터 변경을 되돌리거나 토큰을 철회하는 것은 아닙니다. 인증 오류를 공유할 때 API 키, OAuth 코드와 헤더를 제거하세요. 공식 문서의 bearer 인증 설명은 비밀값을 프롬프트나 저장소에 넣으라는 뜻이 아닙니다. 비밀 저장과 전달 경로는 호스트에서 검증해야 하며 현재 Mirr 조합은 미확인입니다.
새 설정에는 Streamable HTTP 기본 경로를 검토합니다. 공식 문서는 /sse를 이전 클라이언트용 deprecated fallback으로 설명합니다. 전송 오류를 해결하려고 무조건 오래된 경로로 바꾸거나 보조 패키지를 설치하지 마세요. 현재 호스트의 지원과 정확한 오류를 먼저 확인합니다. 패키지가 필요한 다른 클라이언트의 예시는 Mirr에 추가 설치가 필요하다는 증거가 아닙니다. 이 글은 패키지 설치나 실제 연결을 수행하지 않았습니다.
실패 후 재시도와 복구의 구분#
상태 변경 요청이 시간 초과되면 현재 이슈 상태와 댓글을 먼저 조회합니다. 서버에는 반영됐는데 응답만 끊겼을 수 있습니다. 같은 댓글을 다시 올리면 업무 기록이 중복되고 멘션 알림이 반복될 수 있습니다. 대상과 실행 시점, 의도한 내용을 기준으로 반영 상태를 확인하세요. 서비스의 중복 방지 기능이 있다면 공식 계약을 검토하되 MCP가 자동으로 보장한다고 추정하지 않습니다.
잘못 바꿨다면 변경 전 상태와 현재 상태를 비교하고 서비스에서 별도 승인을 받아 수정해야 합니다. /rewind는 외부 이슈를 자동 복구하지 않습니다. 연결 제거와 토큰 철회, 이미 전송된 데이터의 보관도 각각 확인합니다. 감사 기록을 남기기 위해 필요한 정보와 공개 로그에 남기면 안 되는 원문을 구분하세요. 복구했다고 원래 기록이 모든 사본에서 사라진다고 보장할 수는 없습니다.
실제 이슈 전후 비교를 준비하기#
다음은 실행하지 않은 가상 팀의 상태 결정 예시입니다. 이 팀은 구현 중, 검증 대기, 완료를 쓰고, 완료는 “합의한 수락 검사를 모두 확인함”을 뜻한다고 정합니다. 배포는 별도 이슈로 관리합니다. 이는 Linear의 기본 상태나 실제 워크스페이스 정책이 아닙니다. 사용할 때는 해당 팀의 실제 상태 목록과 의미를 대조해야 합니다.
가상 이슈의 과제는 “CSV 금액 형식을 제한하고 잘못된 날짜를 거부한다”입니다. 현재 상태는 구현 중이며 수정 코드는 있지만 통합 검사는 하지 않았다고 가정합니다. 같은 이슈라도 다음 관찰에 따라 제안할 상태가 달라집니다.
| 확인한 사실이라는 가정 | 독립적으로 정한 상태 결정 | 설명에 남길 내용 | 변경하지 않을 것 |
|---|---|---|---|
| 단위 검사만 통과, 통합 검사 미실행 | 검증 대기 제안 | 통과 범위와 필요한 환경 | 완료로 이동하거나 배포됐다고 쓰지 않음 |
| 수락 입력에서 결함 재현 | 구현 중 유지 또는 복귀 제안 | 재현 조건과 실패 기대값 | 기존 수락 조건을 실패 결과에 맞춰 낮추지 않음 |
| 합의한 모든 검사 확인 | 완료 제안 | 검사 자료와 해당 커밋 | 별도 배포 이슈·프로젝트를 함께 완료하지 않음 |
| 실행 직전 다른 담당자가 상태 변경 | 기존 변경안 취소 후 재조회 | 무엇이 달라졌고 어느 판단을 다시 해야 하는지 | 오래된 상태를 기준으로 덮어쓰지 않음 |
표의 결정은 상태를 실제 바꾸라는 명령이 아닙니다. 읽기 전용 연결에서는 이 결정을 초안으로만 남깁니다. 쓰기를 승인받았다면 이슈와 팀의 실제 상태 식별자를 사용하고 변경 후 같은 이슈를 재조회합니다. 실패 후 복구와 중복 댓글 처리의 경계는 앞 절을 따릅니다.
근거: Linear 공식 MCP 문서. 공식 서버의 읽기·쓰기와 인증 범위를 전제로 한 업무 결정 예시입니다.
이슈와 프로젝트·하위 이슈를 구분하기#
같은 가상 팀에 상위 이슈 주간 리포트, 하위 이슈 입력 검증과 보고서 표시, 별도 이슈 배포 확인이 있다고 합시다. 입력 검증이 끝났지만 보고서 표시에는 접근성 검토가 남았다고 정합니다. 이때 입력 검증 이슈의 완료를 상위 목표 전체의 완료로 요약하면 빠진 작업이 숨습니다. 도구에서 부모·자식 관계를 확인한 것과 모든 수락 조건을 확인한 것은 다릅니다.
상위 목표에 어떤 수락 조건이 포함되는지 사람이 검토하는 예입니다. 상태 요약을 댓글로 남길 때는 완료한 범위와 남은 범위를 한 문장 안에 함께 적을 수 있습니다. 예를 들어 “입력 거부 규칙은 확인했고, 보고서 화면 검토와 배포 확인은 남았습니다”는 가정에 맞지만 “주간 리포트 출시 완료”는 맞지 않습니다. 서비스의 객체 관계와 업무 의미를 혼동하지 마세요.
일괄 변경보다 이슈 하나에서 검증하기#
먼저 각 이슈의 수락 조건에 맞춘 변경 제안을 만듭니다. 같은 “검증 대기” 제안이라도 미실행 이유가 다르면 담당자가 취할 행동도 달라집니다.
여러 객체를 바꾸려면 대상 목록과 변경 내용을 사람이 따로 검토해야 합니다. 목록을 실행하는 도중 일부만 반영됐다면 성공한 대상과 미반영 대상을 구분해야 합니다. 다만 이 목록은 트랜잭션으로 여러 이슈를 원자적으로 바꿀 수 있다는 보장이 아닙니다. 선택한 도구의 입력 단위와 실패 결과를 확인해야 합니다. 조회 결과만으로 일괄 변경 승인이나 다른 팀의 권한을 얻지는 않습니다. 읽기 전용 도구 노출과 기반 토큰의 쓰기 차단도 서로 다른 통제이므로 실제 시험에서 어느 경계를 확인했는지 적으세요.
요약의 서법을 원문과 맞추기#
댓글에서 “이 조건이면 해결될 수 있다”를 읽었다면 요약에서도 가능성으로 남겨야 합니다. 이를 “해결됐다”로 바꾸면 상태 변경의 근거가 왜곡됩니다. 담당자 제안, 승인된 결정과 실제 실행 결과를 구분하세요. 날짜와 숫자, 직접 인용은 임의로 바꾸지 않고 원문과 대조합니다. 한국어를 자연스럽게 다듬는 과정에서도 요구와 추측의 강도를 보존해야 합니다. 불명확한 문장은 자신 있게 채우지 말고 확인 질문으로 남깁니다.
가상 날짜 이슈에 “이 입력이면 해결될 수도 있다”는 댓글만 추가됐다면 요약은 여전히 제안입니다. 실제 수정 커밋과 재검사 출력이 연결되지 않았다면 “결함 해결”로 상태를 바꾸는 근거가 되지 않습니다. 반대로 확인한 테스트가 추가됐다면 어떤 조건을 검증했는지 기록에 반영하되 시험하지 않은 입력까지 확대하지 않습니다. 같은 문장을 더 자신 있게 고쳐 쓰는 대신 근거가 바뀌었는지를 보는 것입니다.
“처리해 줘”처럼 목표가 모호한 요청에는 현재 상태, 제안할 목표와 이유를 먼저 제시하세요. 이슈 상태만 바꾸는 요청에 본문 덮어쓰기, 담당자 변경이나 프로젝트 종료를 끼워 넣지 않습니다. 다른 서비스로 공유할 때는 고객 정보와 비공개 링크를 제외할 수 있는지 검토하고 필요한 자료만 전달합니다.
전송 방식과 인증 흐름 확인하기#
Linear 문서는 MCP 서버의 기본 전송이 Streamable HTTP이고, 대화형 설정 흐름은 동적 클라이언트 등록을 포함한 OAuth 2.1을 쓴다고 설명합니다(Linear MCP 문서). 이 글은 실제 설정 화면을 열지 않았으므로, Mirr Code가 같은 흐름을 지원하는지는 확인하지 않았습니다. 연결 전에 전송 방식과 인증 방식을 기록하세요.
다음에 연결할 것#
GitHub MCP 이슈·PR 연결 안내에서도 저장소 접근 권한과 쓰기 전 검토를 확인할 수 있습니다.
관련#
편집 메모 (2026-11-02): 읽기·상태 변경·복구 FAQ와 진단표를 추가했습니다. 실제 설치·인증, 워크스페이스 권한·도구 목록과 이슈 변경 전후 기록은 아직 없습니다.