Paper2Agent Guide: Turn Research Papers and Code into Tested MCP Tools

A research paper can describe a useful method in a few pages, yet applying it to your own data may require hours of repository hunting, dependency setup, notebook editing, and result checking. Paper2Agent is an open project designed to close that gap. It converts papers into agent-readable skills and turns supported research repositories into tested Model Context Protocol tools.

It is not a “drop in any PDF and get an authoritative scientist” service. The Paper2Agent study, published in Nature on September 16, 2026, reports that a substantial fraction of repositories still could not be agentified because of incomplete code, missing documentation, or environments that could not be resolved. This guide uses the official repository and paper as checked on September 19 to explain how to install the project for Codex or Claude Code, choose the right conversion route, and decide whether the result is ready to use.

At a glance
  • A paper-only input becomes a searchable paper skill; an executable repository can become a tested MCP server.
  • The Codex skill location is ~/.agents/skills/paper2agent; Claude Code uses ~/.claude/skills/paper2agent.
  • Provide the exact paper, official repository, tutorial or task, output directory, and resource boundaries instead of asking for an unbounded conversion.
  • A generated tool does not validate a scientific conclusion. A reviewer still needs to inspect execution evidence, input scope, licenses, secrets, and limitations.

Paper2Agent produces more than one kind of artifact

The current top-level skill routes work into two components. Paper2Skill turns a manuscript, supplementary PDFs, spreadsheets, figures, and tables into a structured reading package. It does not execute commands or methods embedded in a paper. Its job is source-faithful extraction, page review, and traceable retrieval. Paper2MCP selects reusable operations from Python, R, or command-line research repositories, binds each operation to existing source code, and builds a tested MCP server with usage documentation.

Goal and inputRouteMain output
Read and query PDFs and supplementsPaper2SkillSKILL.md, continuous text, figures, tables, and a source index
Run official research code on new inputsPaper2MCPTested MCP tools, USAGE.md, and a delivery ZIP
Preserve both explanation and executionCombined routeSeparate skill/ and mcp/ components

If a paper has no public implementation, forcing an MCP build is usually the wrong first step. A reviewed reading skill can still make the evidence easier to navigate. When the authors provide a maintained repository and executable tutorials, the MCP route can turn a documented example into a repeatable operation.

Six-stage concept showing papers and research code moving through environment setup, tutorial execution, tool extraction, independent verification, and MCP server delivery
A six-stage view of source intake, isolated execution, tool wrapping, independent verification, and MCP delivery

What to prepare before installation

The target repository, not Paper2Agent alone, determines the real workload. The official project expects a coding-agent host with skill support, shell access, and parallel agent spawning. You also need Python and Git, plus any R runtime, native command-line tools, data, API access, or GPU required by the selected repository. Define these five items before you start:

  1. Authoritative sources: collect the paper or official URL, supplements, figures, and tables.
  2. Official code: use the repository linked by the authors or journal rather than an automatically selected look-alike fork.
  3. A bounded task: name a tutorial, tutorial URL, or concrete analysis instead of converting everything.
  4. Resource limits: check local memory and storage, GPU requirements, external API charges, and model-usage limits.
  5. Data boundaries: validate with public sample data before considering patient, customer, or proprietary files.

Install the skill for Codex or Claude Code

Clone the repository and copy the entire skill directory. Copying only SKILL.md is insufficient because the route includes scripts, component skills, and reference files.

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/"

Start the coding agent from the workspace where you want the result. Restart the agent if the new skill does not appear. A useful first request names every important boundary:

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.

If the repository needs an API key, place it in the host’s secret mechanism or process environment. Tell the agent the environment-variable name, not the credential itself. The official workflow requires credentials to remain outside generated code, notebooks, reports, and the delivered archive.

What happens during a repository-to-MCP conversion

  1. Repository identification: locate the author-linked code, collect associated resources, and identify the implementation language.
  2. Isolated environment setup: create a project-specific runtime and record dependencies and test configuration.
  3. Tutorial discovery: inspect notebooks, examples, public interfaces, and official tests to select independently useful tasks.
  4. Reference execution: run approved tutorials end to end and preserve inputs, outputs, plots, runtime constraints, and hidden assumptions.
  5. Tool extraction and independent verification: wrap existing functions, scripts, or CLI operations with minimal glue. Fresh verifier agents compare outputs with reference evidence, vary inputs, and test relevant failures.
  6. MCP integration and delivery: launch the server, inspect its tool inventory and schemas, replay acceptance calls, and package the server with USAGE.md.

The distinction matters: Paper2MCP is supposed to bind tools to existing repository code, not invent missing scientific algorithms. The official instructions also require blocked, merged, deferred, and excluded work to be recorded. Passing a selected set of tools does not establish that every method or conclusion in the repository is correct.

Three practical ways to use it

1. Convert one tutorial into a team tool

Suppose a package has a reliable preprocessing and clustering tutorial that your team repeats. Limit the request to that workflow and expose the input file, supported parameters, and output directory. Reviewers should first reproduce the public example, then confirm that the wrapper does not retain fixed paths, constants, cached outputs, or tutorial-specific assumptions when the input changes. The goal is a reusable task, not a thin MCP endpoint for every internal helper function.

2. Build a traceable paper-reading skill

When there is no executable code, or the immediate need is evidence retrieval, use Paper2Skill by itself. Its workflow reviews every page and supplied image, checks reading order, connects captions with figures and tables, and compares exported workbook coordinates with source snapshots. The output should help a user find where a claim came from. It should not fabricate an answer that is absent from the source.

3. Connect methods from two papers

Separate paper agents can be used in a coordinated analysis, such as applying a prediction method from one publication to a dataset described in another. The Nature study demonstrates this direction, but an agent-generated connection is not a confirmed discovery. A human researcher still defines the permissible question and data, checks assumptions and intermediate artifacts, and decides what experimental validation is required.

Conceptual research railway where a paper-skill route and a code-to-MCP route pass through a human review checkpoint before combined delivery
Paper reading and executable MCP routes serve different purposes and should merge only after a human review gate

How to decide whether the result is complete

A new output folder is not completion evidence. For a paper skill, every source page and supplied image must be reviewed, source hashes and links must match, table transformations must be checked, and remaining discrepancies must be adjudicated. The official statuses mechanical_failure, unreviewed, and unresolved_discrepancies describe drafts. A package is deliverable only after it reaches reviewed or reviewed_with_limitations, with those limitations visible.

An MCP server needs runtime evidence as well. Launch it over the expected transport, read the exposed tool inventory and input schemas, extract the ZIP to a fresh location, install its documented dependencies, and replay real acceptance calls. Confirm that every tool maps to an existing function, script, or CLI operation and that failed tasks were not silently removed to create a success report. Finally, trace one small public sample from input file to generated artifacts.

Cost, security, and rights boundaries

  • Cost: do not assume a fixed price or duration. Model calls, the number of tutorials, dependency builds, API use, and GPU execution can all change the total. Start with one tutorial and public sample.
  • Code execution: a research repository and its notebooks are third-party code. Run them in an isolated environment with minimal network and filesystem access.
  • Secrets: provide API keys through environment variables and search logs, notebooks, reports, and the final ZIP for accidental copies.
  • Data: do not introduce sensitive data until public examples pass. For a remote MCP endpoint, separately check where data is sent and retained.
  • Licensing and attribution: public availability does not grant unlimited reuse. Check the licenses for code, datasets, and figures, and preserve citations to the original authors in downstream results and hypotheses.

Troubleshooting in the right order

The skill is missing
Confirm the host-specific path, ensure the complete folder was copied, and restart the coding agent.
Repository selection is ambiguous
Stop repeating automatic discovery and provide the author- or journal-linked URL explicitly.
Environment setup keeps failing
Separate Python or R requirements from system libraries and GPU drivers. Record an unresolvable dependency as a limitation rather than forcing a success state.
The tool runs but produces suspicious output
Reproduce the original tutorial first, then inspect the wrapper for fixed paths, constants, cached results, or unsupported new inputs.
The conversion is too large
Reduce scope to one tutorial or scientific question. Keep incidental internal steps inside the implementation rather than exposing them as separate tools.

Who should try Paper2Agent now?

It is a strong fit for research teams that repeatedly apply public computational methods, engineers turning a stable tutorial into a shared tool, and organizations building traceable reference skills from papers and supplements. It is a poor starting point when the code is private, data rights are unclear, the environment cannot be isolated, or no qualified reviewer can judge the output.

Do not begin with an entire large repository. Choose one well-maintained tutorial and public dataset, then preserve this chain: reproduce the source, bind the tool, verify independently, test a changed input, and document limits. If you want a broader explanation of where MCP tools fit in an agent runtime, see the OpenAI Agents API guide to managed agent runtimes.

한국어판: 한국어로 읽기

Official sources

Sources checked September 19, 2026. The project was public before the Nature publication; this article focuses on the September publication and the repository’s current workflow.

Comments

Post a Comment

Popular posts from this blog

OpenAI Agents API: A Practical Guide to Managed Agent Runtimes

Image
Making one model call is different from operating an agent that reads files, uses tools, and works through several steps. The latter also needs progress records, execution permissions, recovery decisions, and a plan for keeping its outputs. The OpenAI Agents API exposes the Codex agent harness through an OpenAI-managed API. Its value is not simply a different model endpoint: it changes who operates part of the agent runtime. OpenAI announced the public beta on September 10, 2026. This guide explains what the service manages, how it differs from the Agents SDK and Responses API, and how to evaluate it with a small, reviewable task rather than immediately handing it an entire business process. Documentation checked: September 16, 2026. Three things to keep in mind A managed harness coordinates work and tool use; it is not the model itself. Choosing a managed runtime does not decide your data permissions, external-system access, or approval policy for you. Long-running work may benef...
Read more

Diagram Design: Set Up Claude Code or Codex for Clearer Diagrams

Image
Diagram Design is a third-party skill/plugin for coding agents that turns a written brief into an HTML file with inline SVG diagrams. It is not a standalone web-based diagram editor. Its useful promise is narrower: give an agent a specific process and visual direction, then review an editable browser-ready diagram rather than starting from a blank canvas. Three practical takeaways Use in-session slash commands for Claude Code and terminal CLI commands for Codex. Describe the flow, constraints, and output path before asking for drawing. Treat every generated diagram as a draft: verify logic, labels, privacy, and export needs yourself. What it does, and what it does not do The plugin can create several diagram layouts and produces static HTML by default. The inline SVG approach makes the result convenient to open, inspect, and share. Keep the request focused on the decision or process the reader must understand. Existing Mermaid, ...
Read more

Notion Agent Skills: Turn Repeatable Team Work into Reusable Instructions

Image
If your team repeatedly asks AI for the same meeting summary, review, or draft format, copying a prompt eventually becomes fragile. A useful prompt stays in one person’s notes, while the output varies from teammate to teammate. Notion 3.7 Agent Skills , released on September 15, 2026, are designed to turn that working knowledge into reusable instruction pages that Notion Agent can use again. This guide explains where Skills fit for a team that already uses Notion as its document and database hub, how they differ from Custom Agents, and what to check for permissions and cost. An example specification for a meeting-notes skill. Define the input and working rules before adding more instructions. What a Skill is: a repeatable way of working Notion defines a Skill as reusable instructions that teach Notion AI how to complete a type of work. The important detail is that a Skill is a Notion page , not an opaque configuration file. A team can name it, assign an owner, share it, revise it, ...
Read more