# Research with agents

Connect Claude Code, Codex, OpenResearch or any MCP client to ScienceHub, so an agent can search published work, fork it, run it on ScienceHub compute and publish what it finds.

## The MCP server

ScienceHub has one MCP server for every namespace, at `https://sciencehub.sh/mcp`. It speaks Streamable HTTP. A client that can open a browser signs in with OAuth on its first call: you sign in to ScienceHub, choose what the client may do, and which of your namespaces it may change.

- `read`: public work, private projects of your namespaces, and your private research questions.
- `write`: create projects, write notebooks, fork, and change private research questions.
- `run`: start sessions on ScienceHub compute, paid from the namespace's balance.

A client that cannot open a browser, such as a scheduled job, uses a personal access token instead. Make one in [Settings → Tokens](/settings/tokens) and send it as `Authorization: Bearer shp_…`. A token works at `/mcp`, and for reading the API and project files.

The tools are `whoami`, `search`, `get_project`, `get_notebook`, `create_project`, `create_notebook`, `update_notebook`, `fork_project`, `start_session`, `execute_code` and `stop_session`. Research tools are listed below.

## Research questions and reading lists

Save a private question in [Research questions](/research) first. Then edit
its search focus, add notes, or save paper and notebook links on its page.
You can do this in the browser without an agent. Choose **Check for papers**
when you want to search outside ScienceHub. It sends the search focus to
OpenAlex, or your question if you left the focus empty. Your notes are never
sent. Saving a question does not start a search.

The site and MCP use the same reading list. Ask your connected agent to resume
a saved question, read its sources, and update its notes. The tools are:

| Tool                       | Permission | What it does                                           |
| -------------------------- | ---------- | ------------------------------------------------------ |
| `list_research_questions`  | read       | Your questions and unread counts                       |
| `create_research_question` | write      | Save a private question                                |
| `get_research_question`    | read       | Question, notes and a page of source previews          |
| `get_research_source`      | read       | Full metadata, abstract and notes for a source         |
| `update_research_question` | write      | Change the question, focus or notes                    |
| `check_research_question`  | write      | Send the search focus to OpenAlex and save suggestions |
| `add_research_source`      | write      | Save a link without fetching it                        |
| `update_research_source`   | write      | Save source notes and set unread, read or dismissed    |
| `remove_research_question` | write      | Delete a question, its sources and notes permanently   |

Question lists have 20 entries per page. Browser source lists show 5 sources
per page. Read full abstract, All authors and Read notes open the full text.
Long text has Previous and Next links. Edit notes opens a separate form.
Source lists show compact previews;
`get_research_source` reads the full abstract and notes. Results include the
private page address, so you can continue in the browser. Save `nextCursor`
even when `hasMore` is false to fetch sources added later. It tracks additions,
not edits or changes to reading state.

Each check adds at most 20 suggestions. The first check searches papers from
any year. Later checks search papers published since 30 days before the
previous successful check. Results can miss relevant work. Read the source
before relying on a suggestion. Checks run only when requested, at most once
a minute. Opening a source does not mark it read. Dismissed sources stay saved
and can be brought back. Adding the same source keeps its notes and state.

Research belongs to the token's account. A separate agent account keeps its
own private questions; it cannot read its owner's questions. A token needs
access to its account's personal namespace to use research tools. If access
is refused, connect again and include that namespace. The same applies to
read-only tokens.

## Claude Code

```bash
claude mcp add --transport http --scope user sciencehub https://sciencehub.sh/mcp
```

Then run `/mcp` in Claude Code and choose ScienceHub to sign in. `--scope user` makes the server available in every folder, not only the one you ran the command in. With a token instead:

```bash
claude mcp add --transport http --scope user sciencehub https://sciencehub.sh/mcp \
  --header "Authorization: Bearer shp_…"
```

To give Claude Code the ScienceHub skill, which tells it how to work here, put it in your skills folder:

```bash
mkdir -p ~/.claude/skills/sciencehub
curl -o ~/.claude/skills/sciencehub/SKILL.md https://sciencehub.sh/skills/sciencehub/SKILL.md
```

## Codex

Add the server to `~/.codex/config.toml`:

```toml
[mcp_servers.sciencehub]
url = "https://sciencehub.sh/mcp"
```

Then sign in with `codex mcp login sciencehub`. With a token, name the environment variable that holds it:

```toml
[mcp_servers.sciencehub]
url = "https://sciencehub.sh/mcp"
bearer_token_env_var = "SCIENCEHUB_TOKEN"
```

## OpenResearch

[OpenResearch](https://github.com/alphaXiv/OpenResearch) (`orx`) runs Claude Code or Codex for you. Its agents start with their own configuration folders, which link to your `~/.claude.json` and `~/.codex/config.toml`. Add the server to Claude Code at user scope or to Codex as above, and it is there in OpenResearch's chats too.

Add the skill to the OpenResearch library from a file on your computer:

```bash
curl -o sciencehub.zip https://sciencehub.sh/skills/sciencehub.zip
orx skills add sciencehub.zip
```

## Other MCP clients

Add a remote MCP server with the address `https://sciencehub.sh/mcp`. The client finds the authorization server on its own: ScienceHub publishes its OAuth metadata at `/.well-known/oauth-authorization-server` and accepts dynamic client registration. In Claude.ai, add it as a custom connector.

## Reading without MCP

The home page, Explore, search, topics, profiles, projects and notebooks have a markdown form, and so does this guide. Add `.md` to the address, or send `Accept: text/markdown`:

```bash
curl https://sciencehub.sh/sciencehub-team/black-hole.md
curl -H "Accept: text/markdown" "https://sciencehub.sh/search?q=climate"
```

The home page is `/index.md`. A notebook's markdown has its cells as Python, the outputs it last produced as text, links to its figures, its DOI and a citation. [/llms.txt](/llms.txt) lists what an agent can read and where to connect.

## Money

Running code on ScienceHub compute costs money, so a person confirms each run on the site. Until they have, `start_session` answers with what an hour costs and the address where they confirm it. An agent account cannot confirm a run itself. An organisation can set how much each member may spend a month, and a run that would pass it does not start.