@papexlabs/mcp

Papex MCP

@papexlabs/mcp connects an MCP-compatible AI app to Papex. It prepares private Hypothesis, Discovery and Publication drafts, reads public profiles and records, and uploads supporting files you select. You review, edit, sign and choose publication in Papex.

The agent prepares; you decide. It cannot sign a research record as you, accept its own proposals, make rights statements or publish. A signed version can stay private. Provenance and signatures record actions and commitments; they do not establish scientific validity, peer review, ownership or real-world identity. Normal operation needs no blockchain node or user transaction.

This README describes version 0.8.1, including optional research-intake links on prepared drafts. The package is published on npm; no repository access is needed. The source repository is private, but the distributed JavaScript remains inspectable.

Get started

1. Requirements

You need Node.js 22.12 or newer. Your AI app starts the server with npx, which downloads the pinned version on first start. This is a local stdio MCP server; the app starts it as a process. It is not a remote HTTPS MCP endpoint.

2. Connect your AI app

The example below uses the mcpServers format supported by Claude Desktop and Cursor. Keep it in your app's user-local configuration. Other apps may use a different format; see the examples below. In Claude Desktop, open Settings → Developer → Edit Config. In Cursor, use ~/.cursor/mcp.json for user-wide configuration. Preserve any existing server entries.

Merge the papex entry into the app's existing MCP configuration:

{
  "mcpServers": {
    "papex": {
      "command": "npx",
      "args": ["-y", "@papexlabs/mcp@0.8.1"],
      "env": {}
    }
  }
}

Without further settings the server uses Papex at https://api.papex.org and links to https://papex.org. If the app or your network sets HTTPS_PROXY / HTTP_PROXY, requests go through that proxy (hosts in NO_PROXY are reached directly). For another Papex environment, set PAPEX_API_BASE_URL (API requests) and PAPEX_VERIFY_BASE_URL (review, setup and history links) together in env. HTTPS is required except for loopback hosts such as localhost and 127.0.0.1.

This configuration enables public reads, local capsule previews and manual seal instructions. It grants no delegated writes. Local previews can reveal filenames and hashes to your AI app.

Codex configuration

Add this to ~/.codex/config.toml:

[mcp_servers.papex]
command = "npx"
args = ["-y", "@papexlabs/mcp@0.8.1"]
startup_timeout_sec = 30

[mcp_servers.papex.env]

Add any key and grants under [mcp_servers.papex.env]. Check with codex mcp list or /mcp. See the official MCP setup guide.

VS Code with GitHub Copilot configuration

Open MCP: Open User Configuration from the Command Palette. VS Code uses servers rather than mcpServers:

{
  "servers": {
    "papex": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@papexlabs/mcp@0.8.1"],
      "env": {}
    }
  }
}

Use MCP: List Servers to start and check Papex. See the VS Code MCP guide.

For another local MCP app, supply npx with the arguments -y @papexlabs/mcp@0.8.1 in its stdio configuration. This package has no hosted MCP connector URL; a web client cannot directly start the local process.

3. Enable only the permissions you need

On papex.org (or the environment set in env), open Workspace → Connections (/workspace/ai) and add a connection. Papex shows its delegate key once and a separate grant ID for each permission. To prepare private drafts, add these entries to the existing env object:

{
  "PAPEX_DELEGATE_PRIVATE_KEY": "0x…",
  "PAPEX_RESEARCH_DRAFT_GRANT_ID": "…"
}

Replace 0x… and … with the issued values. These snippets are configuration fragments; keep any origins you set in step 2. Public reads do not require a connection.

What you want to enable	Grant environment variable
Prepare private drafts and revisions, including Publication PDFs	PAPEX_RESEARCH_DRAFT_GRANT_ID
Read selected private draft fields and propose changes	PAPEX_RESEARCH_DRAFT_ASSIST_GRANT_ID
Propose supporting artifact metadata	PAPEX_RECORD_ARTIFACT_GRANT_ID
Upload selected supporting files to private quarantine	PAPEX_ARTIFACT_FILE_CUSTODY_GRANT_ID
Seal a selected file set or fingerprint as DELEGATE	PAPEX_SEAL_GRANT_ID
Record content checkpoints and use their local history	PAPEX_CHECKPOINT_GRANT_ID

Every grant is separate and revocable. A seal or checkpoint signature is an agent commitment, not a human research-record signature. A checkpoint grant alone does not authorize automatic capture; see local files and checkpoints.

[!WARNING] Environment values in these configuration files are plain text. The delegate key signs requests locally and is not sent to Papex, but anyone with it can use the connection's active permissions. Keep keys and grant IDs out of source control, shared settings, prompts and screenshots. Revoke the connection in Workspace → Connections if exposed. It cannot grant human signing authority.

4. Check the connection and prepare a draft

Restart the MCP server in your app, then ask: “Check my Papex connection.” papex_setup_delegation reports the configured grants and anything that needs attention. A server with no delegate key reports no connected grant; public reads need a reachable API.

Then ask your agent to prepare the appropriate private draft and open the returned review link. New delegated preparations and proposals require the actual agentModel identifier. It is self-reported: never infer it from the application name or invent a value.

Review the content, authors, files and rights in Papex. Resolve proposals, save your changes, and choose Keep private or Publish publicly before signing the exact version. The agent's handoff is not approval or publication.

Local files and checkpoints

Select only research files you intend the connected AI app to handle. PDF and artifact uploads send the selected bytes to Papex. Seals and checkpoints send commitments and metadata, not file contents or absolute paths; checkpoint history and restore results can expose local paths and content to the connected AI app. That app's handling of these results is outside Papex's control.

To restrict upload and seal roots, set PAPEX_UPLOAD_DIRS to absolute research-directory paths, separated by : on macOS/Linux or ; on Windows. ~ is not expanded. Without this setting, the server's unsafe-root and file-selection checks still apply, but there is no owner-configured directory allowlist. Secret-pattern files and symlinks are refused; do not rely on filename filters to identify every sensitive file.

Checkpoints retain copies locally in ~/.papex/store by default, with a 5 GiB cap. Set PAPEX_STORE_DIR and PAPEX_STORE_MAX_BYTES to change these; the store must be outside the captured directory. Check the tool's contentRetained result: a recorded commitment does not guarantee that a full content copy was retained.

Leave PAPEX_CHECKPOINT_DIRS unset for checkpoints only on explicit request. Setting it to absolute directories, with the same separator rules, additionally permits automatic checkpoints in those directories and their descendants through the connected agent. Host automation hooks can also call the tool. To stop automatic capture, remove those hooks and clear this setting; revoke the checkpoint grant to disable checkpoint access entirely.

Checkpoints without an AI app

The same checkpoint can be taken by a command you run, for work in Jupyter, R or an AI app without hooks. The commands read the same PAPEX_* environment variables as the server (at least the delegate key and PAPEX_CHECKPOINT_GRANT_ID), use the same local store and research line, and obey PAPEX_CHECKPOINT_DIRS when it is set. Set the variables in a profile file only you can read, not on the command line.

npx -y @papexlabs/mcp@0.8.1 checkpoint ~/research/thesis --note "Added replication data"
npx -y @papexlabs/mcp@0.8.1 watch ~/research/thesis
npm install -g @papexlabs/mcp@0.8.1 && papex-mcp hook install ~/research/thesis

• checkpoint takes one now and prints one line, such as checkpoint taken (DELEGATE) · 1a2b3c4d · 12 files · timestamp queued.
• watch takes one when a folder has been quiet for 30 seconds after a change, at most one per folder every 10 minutes (--settle, --min-interval), until you stop it with Ctrl-C.
• hook install adds a git post-commit hook that takes one after every commit. Its note is only the short commit id, never the commit message. The hook calls the installed copy by its full path; hook uninstall removes it.

papex-mcp --help lists the options. Like the tool, these send only the root hash, file count, research-line id, any folder name you set and the note; file contents and paths stay on your computer.

Troubleshooting and support

Symptom	Check
Server will not start	Use Node.js 22.12+. The first start downloads the package and can take longer.
fetch failed in an app that sandboxes MCP servers (Claude Science)	Allow api.papex.org in the app's network settings and restart the app.
env: node: No such file or directory	The app cannot see your Node installation (common with Homebrew or nvm on macOS). Add "PATH": "/opt/homebrew/bin:/usr/bin:/bin", or the folder that contains node, to env.
API requests fail or links open the wrong site	Check both environment URLs and restart the server.
A preparation tool is missing	Ask for papex_setup_delegation; confirm the matching key and grant are active and from the same environment.
Files are refused	Check the explicit file selection, directory allowlists and unsafe-file rules. Do not disable safeguards to force an upload.

For setup help, contact [e-mail]. Report suspected vulnerabilities privately to [e-mail], including the package version, client and reproduction steps. Never include real keys or grant IDs.

License

Apache-2.0 · Papex Labs Ltd. The license text is included as LICENSE in the package.