co-scientist-plugin
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@co-scientist-plugin Start a research session to find new drug targets for Alzheimer's"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
co-scientist plugin
Run a multi-agent scientific research engine from inside your coding agent.
An Agent Plugins 1.0 package that lets Claude Code, Codex CLI, Cursor, VS Code, Copilot and Kiro drive the AI co-scientist engine: generate hypotheses, review them, settle them in an Elo tournament, evolve the winners, and read the synthesis back.
Install · What the agent gets · The design rule · Works with ScientistOS · Contributing
The idea
The AI co-scientist engine is an open re-implementation of Gottweis et al., Nature, 2026. It takes a research goal and runs six specialist agents over it: Generation, Reflection, Ranking, Evolution, Proximity and Meta-review, scheduled by a Supervisor over a durable SQLite task queue.
That engine has a CLI. This package gives it an agent-facing surface, so the thing driving it can be Claude Code or Codex rather than you typing commands:
you → "review hypothesis 3 in that Crohn's session and tell me what breaks"
agent → reads the hypothesis, searches the literature, applies the rubric,
records the review into the engine's database, reports the verdictThe review it wrote is now a row in the same table the engine's own Reflection agent writes to. It counts toward the tournament. The meta-review will see it.
Related MCP server: multivon-mcp
What the agent gets
One MCP server with fifteen tools:
Group | Tools |
Lifecycle |
|
Reading |
|
Writing |
|
Diagnostics |
|
Seven skills carrying the judgement the tools cannot:
Skill | What it does |
| Sharpens a vague goal into a real one, gates on the size of the run, starts and monitors it |
| Reads the ranked output honestly, with five known failure modes checked |
| Reviews against a rubric with score anchors and a verdict decision rule, then records it |
| Runs a three to five turn debate, decides on ordered criteria, records the Elo match |
| Combine, simplify, feasibility, out-of-box, each with its own reference file and failure mode |
| Cross-model Elo bench, and how to read a result without overclaiming |
| Checks that citations say what they are claimed to say, per claim, with verdicts |
The design rule
The engine keeps all state: Elo, the task queue, dedup, embeddings, the token budget, termination. This package reimplements none of it.
Everything an agent produces goes back in through the same repositories the
engine's own agents write to. match_record reuses the engine's Elo module and
its elo_journal idempotency. review_record writes the same Review model
and promotes draft to reviewed exactly as Reflection does.
hypothesis_record derives created_by from whether parents were given.
The skills state the consequence in plain words: output that is not recorded
does not exist. An agent that describes a review in chat without calling
review_record has produced nothing the system can use.
This is what stops the common failure of "port the prompts to skills and call it done". The prompts are not where the quality comes from. The tournament is, and a tournament needs somewhere to keep score.
Works with ScientistOS
This plugin generates and ranks candidate hypotheses. It does not decide what
you are allowed to claim from them, and the difference matters: a hypothesis
can top the tournament and still rest on a mechanism the literature
contradicts. The reading-research-overviews skill lists that failure mode and
several others to check by hand.
ScientistOS makes that check structural instead of advisory. It keeps a typed evidence graph and refuses to record a claim at a strength its lineage does not support.
this plugin → ranked hypotheses, reviews with claim / url / excerpt per source
↓
ScientistOS → hypothesis and source nodes, evidence at its honest level,
an integrity gate before anything gets written upThe two install side by side, since both are skill and MCP packages, and an agent with both loaded gets the whole path. Nothing here requires ScientistOS, and ScientistOS does not depend on this.
Install
No API key, and nothing to decide about billing. If you are reading this you already have the Claude Code or Codex CLI signed in, and that is the whole requirement: the research engine runs its agents through the same subscription your coding agent uses.
python3.12 -m venv .venv
source .venv/bin/activate
pip install "co-scientist @ git+https://github.com/Kaimen-Inc/Co-Scientist.git"
pip install "co-scientist-plugin @ git+https://github.com/Ahmad-Jaradat-Space/co-scientist-plugin.git"
co-scientist initOn first connection the server looks for a working backend. Finding none, it
adopts whichever agent CLI is installed and signed in, writes that choice to
~/.co-scientist/config.toml, and gets on with it. An existing provider =
line is never touched, so a setup you configured yourself is left alone. Set
COSCI_AUTO_BACKEND=0 to turn the whole thing off.
If doctor still reports no backend, sign the CLI in (claude, or
codex login) rather than reaching for a key. It will also report a local hash
embedder, which is the expected keyless state: dedup catches repeated wording
but not two hypotheses that say the same thing differently.
Everything stays on your machine: SQLite under ./data, no account, no service
to sign up for, and no traffic beyond the model calls your CLI was already
making.
config/subscription.toml is the same choice
written out by hand, with the model ids pinned rather than left to the alias
your CLI resolves. Point the engine at it with
export COSCI_CONFIG=/path/to/config/subscription.toml.
A metered API works too: set a provider and key in
~/.co-scientist/config.toml before first run and auto-selection stays out of
the way. estimate_cost then prices the run against a budget, and the skills
ask for a go-ahead on spend rather than on time. See the
engine's backend guide.
Codex CLI
codex plugins install ./co-scientist-pluginClaude Code
ln -s "$PWD/skills/"* ~/.claude/skills/
claude mcp add co-scientist -- co-scientist-mcpAnything else
Any client that reads Agent Plugins 1.0 loads the directory as it is. Any client
that reads SKILL.md and MCP config separately can take skills/ and mcp.json
on their own.
Configuration
The server reads the engine's config. Set these in the env block of your
mcp.json if you need them:
Variable | Effect |
| Path to an extra TOML config to overlay |
|
|
| Seconds to wait for a spawned run to register, default 120 |
|
|
Read-only installs
A session makes hundreds of model calls and keeps running after the conversation ends. On a shared machine, or anywhere an agent should not be able to start one on its own:
co-scientist-mcp --read-onlyReads keep working; session_start and session_resume refuse with an
explanation.
Virtualenv paths
mcp.json calls co-scientist-mcp, which assumes the console script is on
PATH. If your agent does not activate the virtualenv, use an absolute path:
{
"command": "/path/to/.venv/bin/co-scientist-mcp",
"args": []
}Development
pip install -e ".[dev]"
ruff check coscientist_plugin tests
pytest -q
co-scientist-plugin-validateEvery test runs offline against a throwaway database. No key, no network, no model calls.
Three checks guard this package:
co-scientist-plugin-validatechecks spec conformance: the ten permitted manifest fields, transport types, skill frontmatter, name and directory agreement, body length, and that every relative link resolves and stays one level deep.tests/test_plugin.pychecks what a validator cannot: that no skill tells an agent to call an MCP tool or an engine command that does not exist, and that the recording discipline is actually stated in the skills that write.tests/test_server.pycovers the invariants the design rests on: zero-sum Elo, idempotency per round, cross-session refusal, evidence without an excerpt refused, and state transitions that never drag a ranked hypothesis backwards.
Relationship to the engine
This repository is the plugin layer only. The engine it drives lives at
Kaimen-Inc/Co-Scientist and is a
separate project under the same licence. See NOTICE.
Neither project is affiliated with Google or with the paper's authors. Hypotheses either one produces are a starting point for a scientist, not a finding.
Licence
Available Tools
15 toolsdoctorA
Check the install: which LLM backend is configured, whether its credentials resolve, whether embeddings are real or the hash fallback, and where the database lives. Run this first when anything fails.
Inputs: no named parameters.
estimate_costA
Pre-flight size of a session under the current config: calls and tokens per agent, and how long it may run. On a metered API backend it also prices it. Run this before session_start and show the user.
Inputs: no named parameters.
feedback_addA
Inject researcher feedback into a session. A running session picks it up on its next planning step; a paused one picks it up on resume. kind='pin' or 'rejection' with a target also moves that hypothesis's state.
Inputs: text (required), session_id (required), kind, target.
hypotheses_listA
List a session's hypotheses ranked by Elo, with title, summary, state, matches played and dedup cluster. Bodies are omitted; use hypothesis_get.
Inputs: session_id (required), limit, state, offset.
hypothesis_getA
One hypothesis in full: statement, detailed text, citations, Elo history, every review recorded against it, and its tournament matches. Read this before reviewing or ranking it.
Inputs: hypothesis_id (required), include_matches.
hypothesis_recordA
Add a hypothesis to a session, in the same table Generation and Evolution write to. It enters as a draft, gets reviewed, and then competes in the tournament like any other. Set parent_ids when it derives from existing hypotheses, which is what makes it an Evolution result rather than a fresh idea. Recording is what makes a hypothesis real: an idea only described in chat is never reviewed, ranked, or seen by the meta-review.
Inputs: title (required), summary (required), strategy (required), full_text (required), +3 more.
match_recordA
Record the outcome of a head-to-head comparison between two hypotheses and apply the Elo update. Compare them on the paper's criteria (correctness, novelty, testability, and how well each survives its reviews) and give the rationale. Idempotent per (pair, round_id): recording the same pair twice under the same round moves no Elo.
Inputs: hyp_a (required), hyp_b (required), winner (required), rationale (required), +2 more.
overview_getA
The final research overview for a session: the meta-review synthesis of the ranked hypotheses. Only exists once the session has finalized.
Inputs: session_id (required).
review_recordA
Record a review against a hypothesis, in the same table and format the Reflection agent writes. Every factual claim in evidence needs a url and an excerpt you actually read. A 'full' review on a draft hypothesis also promotes it to reviewed. Do not report a review to the user without recording it first, or the tournament and meta-review will never see it.
Inputs: body (required), kind (required), hypothesis_id (required), scores, +4 more.
session_abortA
Abort a session for good. The main loop exits at its next check.
Inputs: session_id (required).
session_listA
List sessions newest first, with status, hypothesis count, top Elo and budget spent. Use this to find a session id the user refers to by topic.
Inputs: limit.
session_pauseA
Pause a running session. Workers drain and the loop sleeps until resumed.
Inputs: session_id (required).
session_resumeA
Resume a paused or interrupted session. The engine reclaims expired task leases and continues where it stopped. Returns immediately; poll session_status.
Inputs: session_id (required).
session_startA
Start a new research session from a natural-language goal. The engine runs the full Generation, Reflection, Elo tournament, Evolution and Meta-review loop in a detached process; this returns as soon as the session id exists. Poll session_status for progress. It runs for minutes to hours, so agree the scale with the user first: call estimate_cost.
Inputs: goal (required), n_initial, budget_usd, concurrency, +2 more.
session_statusA
Progress for one session: status, task counts by state, hypothesis counts by state, matches played, Elo spread, budget spent, and whether the final overview exists yet. This is the polling tool.
Inputs: session_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Tools are mostly distinct by resource and action (sessions vs hypotheses vs reviews vs matches). Minor overlap between session_pause/session_abort and hypothesis_record/review_record, but descriptions are detailed enough to avoid misselection.
Most tools follow a noun_verb pattern (session_list, hypotheses_list, hypothesis_get, review_record), but session_resume, session_start, session_pause, session_abort are verb-first. doctor breaks the pattern entirely. Consistent within each resource group, mixed across groups.
15 tools for a complex scientific research orchestration server. Each tool maps to a distinct lifecycle step: session management (7), hypothesis operations (4), review/match/feedback (3), overview (1), cost estimation (1), diagnostics (1). Well-scoped for the complexity.
Covers the full session lifecycle (start, poll, pause, resume, abort), hypothesis CRUD (list, get, record), review and tournament operations. Missing explicit update/delete for hypotheses or sessions, but the domain (adding to a persistent tournament) doesn't require them. Overview_get exists only after finalization; no explicit wait/finalize tool but polling covers it.
Maintenance
Related MCP Connectors
MCP server for building and testing AI agents with multi-model experimentation and insights.
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
MCP server for AI dialogue using various LLM models via AceDataCloud
Official MCP server for Agentwork — delegate tasks to AI agents with human-in-the-loop
Related MCP Servers
- AlicenseAqualityBmaintenanceAn MCP server that lets Claude Code consult stronger AI models (o3, Gemini 2.5 Pro, DeepSeek Reasoner) when you need deeper analysis on complex problems.1148MIT

multivon-mcpofficial
AlicenseAqualityBmaintenanceMCP server that gives AI coding agents direct access to evaluation tools.23Apache 2.0- AlicenseAqualityDmaintenanceMCP server that lets Claude Code ask GPT Codex for adversarial planning, code review, debugging, research, and risk triage without leaving your project workflow.910 npm2MIT
- AlicenseNot gradedqualityBmaintenanceMCP server enabling Claude to consult Codex (GPT-5.x) mid-task for second opinions, plan/diff review, brainstorming, and codebase exploration via structured debates and permission-controlled interactions.2MIT