Paper2Agent 사용법: 논문과 연구 코드를 검증된 MCP로 바꾸는 법

연구 논문을 읽고 “내 데이터에도 이 방법을 적용해 보고 싶다”고 생각한 뒤 실제 실행까지 가는 길은 길다. 공식 코드 저장소를 찾고, 맞는 버전의 실행 환경을 만들고, 노트북의 예제 값을 내 입력값으로 바꾸고, 결과가 논문과 일치하는지 확인해야 한다. Paper2Agent는 이 간격을 줄이기 위해 논문과 연구 코드를 에이전트가 읽을 수 있는 스킬과 실행 가능한 MCP 도구로 변환하는 공개 프로젝트다.

다만 “PDF를 넣으면 언제나 믿을 수 있는 연구 에이전트가 완성된다”는 제품은 아니다. 2026년 9월 16일 Nature에 정식 게재된 논문도 불완전한 코드, 부족한 문서, 해결할 수 없는 환경 문제 때문에 상당수 저장소가 변환에 실패할 수 있다고 밝힌다. 이 글은 9월 19일 기준 공식 저장소와 논문을 바탕으로, Codex 또는 Claude Code에서 Paper2Agent를 설치하고 어디까지 맡길지 판단하는 순서를 정리한다.

핵심 요약
  • 논문만 있으면 검색 가능한 paper skill, 코드 저장소가 있으면 검증된 도구를 담은 MCP server를 만든다.
  • Codex 설치 경로는 ~/.agents/skills/paper2agent, Claude Code는 ~/.claude/skills/paper2agent다.
  • 좋은 결과의 핵심은 “논문 전체를 알아서 처리해 줘”가 아니라 대상 논문·공식 저장소·튜토리얼·출력 폴더·자원 제한을 명확히 주는 것이다.
  • 생성된 도구는 논문의 결론을 보증하지 않는다. 실행 로그, 원본 예제와의 비교, 입력 범위, 라이선스와 민감정보 경계를 사람이 검토해야 한다.

Paper2Agent가 만드는 것은 하나가 아니다

현재 저장소의 최상위 스킬은 입력에 따라 두 작업으로 갈라진다. Paper2Skill은 본문 PDF, 보충자료, 표와 그림을 구조화된 읽기 패키지로 바꾼다. 이 경로는 논문에 적힌 명령이나 코드를 실행하지 않고, 페이지별 검토와 출처 추적에 초점을 둔다. Paper2MCP는 Python·R·명령줄 기반 연구 저장소에서 재사용할 작업을 고르고, 기존 구현을 최소한의 래퍼로 감싼 뒤 실제 실행과 독립 검증을 거쳐 MCP 서버를 만든다.

입력과 목적선택 경로주요 결과
PDF·보충자료를 정확히 읽고 질의Paper2SkillSKILL.md, 연속 본문, 표·그림 자산, 출처 색인
공식 연구 코드를 새 입력에 실행Paper2MCP검증된 MCP 도구, 사용 문서, 전달용 ZIP
논문 설명과 실행 도구를 함께 보존두 경로 결합skill/과 mcp/를 분리한 에이전트 패키지

따라서 논문에 공개 코드가 없다면 억지로 실행 도구부터 만들기보다 읽기 스킬을 먼저 만드는 편이 맞다. 반대로 잘 관리된 저장소와 실행 가능한 튜토리얼이 있다면 MCP 경로가 “설명”을 “반복 가능한 작업”으로 바꾸는 데 유리하다.

논문과 연구 코드가 환경 구성, 튜토리얼 실행, 도구 추출, 독립 검증을 거쳐 MCP 서버가 되는 여섯 단계 개념도
원본 자료 수집부터 독립 검증과 MCP 연결까지, Paper2Agent의 작업을 여섯 구역으로 나눈 개념도

시작 전에 준비할 것

Paper2Agent 자체보다 대상 연구 저장소의 요구사항이 작업 난도를 좌우한다. 공식 안내는 스킬과 셸을 지원하고 병렬 하위 에이전트를 실행할 수 있는 코딩 에이전트 호스트, Python과 Git, 그리고 대상 코드가 요구하는 R·CLI·데이터·API·GPU 접근을 전제로 한다. 아래 다섯 가지를 먼저 결정하면 불필요한 전체 변환을 줄일 수 있다.

  1. 공식 원문: 논문 PDF 또는 공식 URL, 보충자료와 표 파일을 한곳에 모은다.
  2. 공식 코드: 논문 저자나 저널이 연결한 저장소인지 확인한다. 이름이 비슷한 포크를 자동 선택하게 두지 않는다.
  3. 한정된 작업: “전부 변환”보다 필요한 튜토리얼 이름이나 URL, 수행하려는 분석을 정한다.
  4. 실행 자원: 로컬 CPU·메모리·저장 공간, GPU 필요 여부, 외부 API 비용과 사용 한도를 확인한다.
  5. 데이터 경계: 환자·고객·사내 데이터는 예제 실행에 넣지 않는다. 먼저 공개 예제 데이터로 검증한다.

Codex와 Claude Code에 설치하는 정확한 순서

터미널을 열고 저장소를 받은 뒤 스킬 폴더 전체를 복사한다. 하위의 스크립트와 참고 파일도 필요하므로 SKILL.md 하나만 옮기면 안 된다.

git clone https://github.com/jmiao24/Paper2Agent.git
cd Paper2Agent

# Codex
mkdir -p "$HOME/.agents/skills/paper2agent"
cp -R skills/paper2agent/. "$HOME/.agents/skills/paper2agent/"

# Claude Code를 쓸 때는 아래 경로 사용
mkdir -p "$HOME/.claude/skills/paper2agent"
cp -R skills/paper2agent/. "$HOME/.claude/skills/paper2agent/"

그다음 분석할 작업 폴더에서 코딩 에이전트를 시작한다. 설치한 스킬이 목록에 보이지 않으면 세션을 다시 시작한다. 최초 요청에는 논문, 공식 코드, 결과 폴더와 범위를 모두 적는다.

Use the paper2agent skill to agentify this paper and its associated files.
Paper: <PAPER_URL_OR_LOCAL_FILES>
Code repository: <OFFICIAL_GITHUB_URL_OR_LOCAL_PATH>
Output directory: <PROJECT_DIR>
Focus on: <TUTORIAL_TITLE_OR_TASK>
Follow the skill verification and final-delivery requirements.

API 키가 필요한 저장소라면 프롬프트나 코드 파일에 값을 직접 붙이지 말고 호스트의 비밀 저장소나 환경 변수에 둔다. 요청에는 실제 키 대신 변수 이름만 알려 준다. 공식 안내는 자격증명이 생성 코드, 노트북, 보고서와 전달용 ZIP 밖에 남도록 요구한다.

변환 과정에서 실제로 일어나는 여섯 단계

  1. 저장소 확인: 논문과 보충자료에서 공식 코드 위치를 찾고 언어와 관련 파일을 분류한다.
  2. 격리 환경 구성: 프로젝트 전용 환경을 만들고 의존성과 테스트 설정을 기록한다.
  3. 튜토리얼 탐색: README의 문장만 믿지 않고 노트북, 예제, 공식 테스트 중 재사용 가치가 있는 작업을 고른다.
  4. 원본 실행: 선택한 예제를 끝까지 실행해 입력, 수치, 그림, 파일과 숨은 전제를 기준 결과로 남긴다.
  5. 도구 추출과 독립 검증: 기존 함수나 CLI를 최소 래퍼로 감싸고, 구현자와 다른 검증 에이전트가 원본 결과·변형 입력·실패 조건을 확인한다.
  6. MCP 통합과 전달: 서버를 실제로 기동해 도구 목록과 입력 스키마, 저장된 승인 호출을 검사하고 USAGE.md와 ZIP을 만든다.

중요한 차이는 “코드를 새로 발명하는 것”이 아니라 저장소에 이미 있는 구현에 도구를 결합한다는 점이다. 공식 Paper2MCP 지침은 저장소에 없는 과학 알고리즘으로 빈틈을 메우지 말고, 막히거나 제외한 기능과 이유를 기록하라고 요구한다. 검증한 몇 개 도구가 통과했다고 저장소 전체가 정확하다고 해석해서도 안 된다.

세 가지 실용적인 활용 예시

1. 특정 튜토리얼만 팀용 도구로 만들기

예를 들어 분석 패키지의 “전처리와 군집화” 튜토리얼만 골라 입력 파일, 주요 매개변수와 결과 폴더를 받는 MCP 도구로 만들 수 있다. 목표는 패키지 전체를 감싸는 것이 아니라 팀이 반복하는 한 흐름을 재현하는 것이다. 검토자는 공개 예제 데이터에서 단계 순서, 결과 파일, 주요 도표가 기준과 맞는지 확인하고, 다른 입력에서도 경로와 값이 하드코딩되지 않았는지 살펴야 한다.

2. 논문과 보충자료를 검색 가능한 내부 참고자료로 만들기

실행 코드가 없거나 계산보다 근거 검색이 중요하다면 Paper2Skill만 선택한다. PDF 페이지마다 읽기 순서, 표와 캡션 연결, 수식과 코드 들여쓰기를 검토하고, 스프레드시트는 숨은 행과 수식의 저장값까지 원본 좌표와 비교한다. 결과는 논문에 없는 답을 만들어 내는 도구가 아니라, 어느 표와 문장에서 근거를 찾았는지 추적하기 쉬운 읽기 패키지다.

3. 두 논문의 방법을 한 분석에서 연결하기

각 논문을 별도 에이전트로 만든 뒤 한쪽의 예측 결과를 다른 쪽 데이터 해석에 쓸 수 있다. Nature 논문은 이런 협업 사례를 제시하지만, 이것을 자동 발견의 확정 증거로 받아들이면 안 된다. 연구자는 연결할 질문과 허용된 데이터 범위를 정하고, 중간 산출물의 의미와 통계 가정, 최종 가설의 실험적 검증 필요성을 판단해야 한다.

논문 읽기 스킬 경로와 연구 코드 MCP 경로가 사람의 검토 관문을 거쳐 결합되는 선택 구조 개념도
논문 전용 스킬과 코드 실행 MCP는 역할이 다르며, 결합 전에는 사람의 검토 관문이 필요하다

완료 여부는 무엇으로 확인할까

폴더가 생겼다는 사실만으로 완료된 것은 아니다. 논문 스킬은 모든 페이지와 제공 이미지의 검토 표시, 원본 해시, 링크와 표 변환, 남은 차이에 대한 판정이 필요하다. 공식 검증 상태 중 mechanical_failure, unreviewed, unresolved_discrepancies는 초안으로 봐야 한다. reviewed 또는 제한이 문서화된 reviewed_with_limitations가 되어야 전달 가능한 상태다.

MCP 쪽은 더 엄격하다. 실제 서버를 표준 입출력 방식으로 기동하고, 노출된 도구와 입력 스키마를 읽고, 새 위치에 ZIP을 풀어 의존성을 설치한 뒤 저장된 승인 호출을 다시 실행해야 한다. 각 도구가 기존 코드의 어느 함수·스크립트·CLI에 연결되는지, 실패한 작업을 성공처럼 숨기지 않았는지도 확인한다. 마지막으로 작은 공개 샘플 하나를 사용해 입력 파일부터 결과 파일까지 따라가 보는 것이 좋다.

비용·보안·지식재산권에서 놓치기 쉬운 점

  • 비용: 고정 요금이나 보편적인 실행 시간을 가정하지 않는다. 모델 호출량, 튜토리얼 수, 의존성 빌드와 GPU 사용에 따라 달라지므로 한 튜토리얼과 공개 샘플로 시작한다.
  • 코드 실행: 연구 저장소와 노트북은 제3자 코드다. 격리 환경에서 실행하고 네트워크 접근과 쓰기 가능한 폴더를 최소화한다.
  • 비밀정보: API 키는 환경 변수로만 주고 로그, 노트북, 결과 ZIP에 포함되지 않았는지 검색한다.
  • 데이터: 공개 예제로 통과하기 전에는 개인정보나 비공개 연구 데이터를 넣지 않는다. 원격 MCP를 쓸 때는 전송 위치와 보존 정책도 따로 확인한다.
  • 권리와 인용: 공개 저장소라도 라이선스가 다를 수 있다. 코드·데이터·그림의 허용 범위를 확인하고 결과와 새 가설에서 원 저자와 논문을 계속 인용한다.

자주 막히는 상황과 해결 순서

스킬이 보이지 않는다
호스트별 경로와 폴더 전체 복사 여부를 확인한 뒤 코딩 에이전트를 다시 시작한다.
저장소 선택이 모호하다
자동 탐색을 반복하지 말고 논문 저자나 저널이 연결한 공식 URL을 직접 지정한다.
환경 설치가 계속 실패한다
Python·R·시스템 라이브러리·GPU 요구 버전을 나누어 확인한다. 해결할 수 없는 의존성은 제한으로 남기고 성공 상태를 강제로 만들지 않는다.
도구는 실행되지만 결과가 이상하다
원본 튜토리얼의 입력과 결과를 먼저 재현하고, 하드코딩된 경로·상수·캐시 결과가 새 입력에 남았는지 검사한다.
전체 작업이 너무 크다
한 튜토리얼 또는 한 과학적 질문으로 범위를 줄인다. 독립적으로 유용하지 않은 중간 단계는 별도 도구로 노출하지 않는다.

누가 지금 써볼 만한가

공개 코드가 있는 계산 연구를 반복 적용하는 연구팀, 복잡한 튜토리얼을 팀 표준 도구로 바꾸려는 엔지니어, 논문과 보충자료를 근거 추적 가능한 스킬로 보관하려는 조직에 적합하다. 반면 코드가 비공개이거나, 데이터 권한이 불명확하거나, 정답을 독립적으로 판정할 전문가가 없다면 자동 변환보다 원문 검토와 환경 정리부터 하는 편이 안전하다.

처음부터 대형 저장소 전체를 변환하지 말자. 공개 예제와 잘 관리된 튜토리얼 하나를 고르고, 원본 재현 → 도구 연결 → 독립 검증 → 새 입력 시험 → 제한 기록 순서가 끝까지 유지되는지 보는 것이 가장 현실적인 시작이다. MCP가 에이전트 실행 환경에서 어떤 역할을 하는지 먼저 정리하고 싶다면 OpenAI Agents API와 관리형 에이전트 실행 환경 가이드도 함께 참고할 수 있다.

English version: Read this guide in English

공식 자료

자료 확인일: 2026년 9월 19일. 프로젝트는 Nature 게재 이전부터 공개되어 있었으며, 이 글은 9월의 정식 논문 게재와 현재 저장소 지침을 기준으로 작성했다.

댓글

댓글 쓰기

이 블로그의 인기 게시물

Diagram Design 사용법: Claude Code·Codex로 다이어그램 만드는 순서

이미지
Diagram Design은 Claude Code나 Codex 같은 코딩 에이전트에 다이어그램 제작 규칙을 더하는 외부 스킬·플러그인입니다. 별도의 웹 편집기에서 도형을 끌어다 놓는 방식이 아니라, 설명할 구조와 목적을 전달하면 에이전트가 HTML·SVG 기반 결과물을 만들도록 돕습니다. 자동화 흐름을 문서에 넣고 싶은데 상자 배치와 색상 정리에 시간을 쓰고 있다면 살펴볼 만합니다. 다만 보기 좋은 그림과 정확한 설계는 다릅니다. 여기서는 설치부터 첫 요청, 결과 검토와 내보내기까지 구분해 정리합니다. 자료 확인: 2026년 9월 16일 · 공식 README·사용 가이드 기반 안내입니다. 먼저 알아둘 세 가지 Diagram Design 자체가 AI 모델은 아닙니다. 사용할 코딩 에이전트가 먼저 준비돼 있어야 합니다. 처음에는 작은 흐름 하나를 정적 HTML로 만든 뒤 검토하는 편이 좋습니다. 공개 저장소라는 사실과 모델 사용료가 무료라는 말은 다릅니다. 1. 어떤 작업에 쓰면 좋을까? 공식 문서는 아키텍처, 흐름도, 시퀀스, 데이터 모델 등 여러 유형을 제공합니다. 기본 결과는 정적 HTML이며, Mermaid·draw.io·Excalidraw 자료를 선택한 크기와 상세도에 맞춰 다시 그리는 기능도 안내합니다. 모든 요소를 그대로 옮기는 단순 변환과는 다릅니다. 설명할 내용 선택 기준 문의 처리나 업무 자동화 순서 처리 단계와 분기가 보이는 흐름도 앱·서버·데이터베이스의 관계 구성 요소와 연결을 보여주는 아키텍처 시간 순서에 따른 요청과 응답 메시지 순서를 구분하는 시퀀스 옵션 두 개의 장단점 그림보다 비교표가 명확할 수 있음 공식 갤러리의 콘텐츠 사이트 아키텍처 예제. © 2025 Cathryn Lavery, MIT License. 원본 예제 보기 이 예제는 단순한 상자 나열이 아닙니다. Reader에서 들어온 요청, Astro Origin이 읽는 MDX 문서와 CMS, 다시 돌아가는 응답을 선 종류와 라벨로 구분합니다. 자신의 결과물에서도 ...
자세한 내용 보기

OpenAI Agents API란? 관리형 에이전트 실행 환경 이해하기

이미지
모델에 질문을 한 번 보내는 것과, 파일을 읽고 도구를 호출하며 여러 단계의 작업을 끝내는 에이전트를 운영하는 것은 다른 문제입니다. 후자에서는 작업 기록, 실행 권한, 중간 실패, 결과물 보관까지 설계해야 합니다. OpenAI Agents API는 Codex의 에이전트 하네스를 OpenAI가 관리하는 API로 사용할 수 있게 하는 선택지 입니다. OpenAI는 2026년 9월 10일 Agents API 공개 베타를 발표했습니다. 이 글에서는 설치 명령을 나열하기보다 무엇을 맡길 수 있는지, Agents SDK·Responses API와 어떻게 다른지, 어떤 작은 업무로 도입 여부를 판단하면 좋을지 살펴봅니다. 자료 확인: 2026년 9월 16일 · 공식 발표와 개발자 문서 기준 먼저 기억할 핵심 관리형 하네스는 모델 자체가 아니라 작업을 이어 가고 도구를 쓰도록 조율하는 실행 기반입니다. 실행 환경을 선택할 수 있어도 도구 권한, 외부 시스템 접근, 승인 기준은 개발자가 정해야 합니다. 긴 작업에 유용한 선택지이지만, 단발성 호출까지 모두 옮길 필요는 없습니다. 1. 관리형 하네스는 무엇을 관리할까? 하네스는 에이전트가 입력을 받고, 필요한 도구를 사용하고, 중간 결과를 다음 단계에 반영하도록 돕는 실행 틀입니다. 공식 개요는 세션, 작업 조율, 컨텍스트 압축, 복구를 OpenAI가 관리하고 애플리케이션은 도구와 실행 환경을 제공하거나 선택한다고 설명합니다. 따라서 “더 강한 모델을 호출하는 API”보다는 에이전트 운영 책임을 나누는 방식 으로 이해하는 편이 정확합니다. Agent: 사용할 모델, 지시문, 도구와 MCP 서버를 정하는 구성입니다. Environment: 파일을 다루고 명령을 실행하는 선택적 샌드박스나 컴퓨터 환경입니다. Session: 여러 차례 입력을 받으며 작업을 이어 갈 수 있는 지속적인 에이전트 인스턴스입니다. Events와 items: 세션에 전달된 입력과 생성된 출력을 추적하는 자료입니다. 예를 들어 첫 요청에...
자세한 내용 보기

Notion Agent Skills 사용법: 팀의 반복 업무를 재사용 가능한 지침으로 만드는 법

이미지
AI에게 매번 같은 형식의 회의 요약, 검토, 초안을 요청한다면 프롬프트를 복사해 붙이는 방식은 오래 버티기 어렵습니다. 누군가가 잘 만든 요청문은 개인의 노하우로 남고, 팀원마다 결과 형식도 달라지기 쉽습니다. 2026년 9월 15일 공개된 Notion 3.7의 Agent Skills 는 이 문제를 “재사용 가능한 지침 페이지”로 풀려는 기능입니다. 한 번 정의한 업무 방식과 참고 자료를 스킬로 저장하고, 필요할 때 Notion Agent가 불러 쓰도록 합니다. 이 글은 Notion을 이미 문서·데이터베이스 허브로 쓰는 팀이 스킬을 어디에 쓰면 좋은지, 기존 Custom Agent와 어떻게 구분할지, 권한과 비용을 무엇부터 점검할지를 설명합니다. 회의록 정리 스킬에 넣을 지침서 예시. 기능 설명보다 어떤 입력을 받고 어떤 기준을 지킬지 먼저 정합니다. 먼저 이해할 것: 스킬은 ‘반복 가능한 일하는 방식’이다 Notion은 스킬을 특정 유형의 일을 수행하도록 Notion AI를 가르치는 재사용 가능한 지침이라고 설명합니다. 스킬의 본체는 특별한 코드 파일이 아니라 Notion 페이지 입니다. 따라서 기존 문서처럼 제목을 붙이고, 소유자를 정하고, 동료와 공유하고, 수정 이력을 관리할 수 있습니다. 예를 들어 “월간 사업 검토를 우리 팀의 지표 순서로 작성한다”, “제품 제안서를 디자인·개발 기준으로 비평한다”, “신규 입사자 체크리스트를 회사 정책에 맞게 만든다” 같은 규칙을 한 페이지에 담습니다. 핵심은 단순한 템플릿과 다릅니다. 템플릿이 빈 문서의 모양을 복제한다면, 스킬은 Agent가 요청을 해석할 때 참고할 판단 기준과 작업 순서 를 제공합니다. 평소에는 Agent 채팅에서 / 를 입력해 원하는 스킬을 고르고, 필요한 맥락을 덧붙여 실행할 수 있습니다. 자동 사용은 설명(Description)이 있는 스킬 데이터베이스의 스킬에서 기본적으로 켜집니다. 독립된 스킬 페이지는 먼저 스킬 데이터베이스로 옮기고 설명을 추가해야 하며, Agent는 이 설...
자세한 내용 보기