rotifer-mcp-server

Quick Start

Cursor

Add to `.cursor/mcp.json`:

{
  "mcpServers": {
    "rotifer": {
      "command": "npx",
      "args": ["@rotifer/mcp-server"]
    }
  }
}

Claude Desktop

Add to `claude_desktop_config.json`:

{
  "mcpServers": {
    "rotifer": {
      "command": "npx",
      "args": ["@rotifer/mcp-server"]
    }
  }
}

Windsurf / Other MCP Clients

Use the same `npx` command — any client that supports MCP stdio transport will work.

What Can It Do?

Create and run an agent in one conversation

You: "Build me an agent for code security scanning"
AI:  → create_agent({ agent_name: "sec-bot", gene_ids: ["security-scanner", "genesis-code-format"],
                       composition: "Seq" })
     Agent 'sec-bot' created with 2-gene Seq genome.

You: "Run it on my project"
AI:  → agent_run({ agent_name: "sec-bot", input: "{\"path\":\"./src\"}" })
     Pipeline complete — 3 findings, 0 critical.

Search, compare, and compose genes

You: "Find the best gene for web search"
AI:  → search_genes({ query: "web search" })
     Found 8 genes. Top match: genesis-web-search (F(g) = 0.87, Native)

You: "Compare it against the lite version"
AI:  → compare_genes({ gene_ids: ["...", "..."] })
     Side-by-side: success rate, latency, fitness breakdown

Full gene lifecycle from your IDE

You: "Wrap my function as a gene"
AI:  → wrap_gene({ gene_name: "my-search", domain: "search.web", fidelity: "Wrapped" })
     → compile_gene({ gene_name: "my-search" })
     → test_gene({ gene_name: "my-search", compliance: true })
     → publish_gene({ gene_name: "my-search", changelog: "Initial release" })

Tools (31)

Discovery & Analytics

Local Workspace

Gene Lifecycle

Agent Composition

Authentication & Analytics

Resources (7)

MCP Resources let AI clients reference Rotifer data as context:

Each resource returns what the tool of the same job returns, so a declared tool

set covers both: with `--tools=evolve`, `rotifer://genes/{gene_id}/stats`,

`rotifer://developers/{username}` and `rotifer://leaderboard` disappear from the

listing and are refused if read directly, because `get_gene_stats`,

`get_developer_profile` and `get_leaderboard` were not asked for.

`rotifer://version` always answers — it is the server describing itself, not a

capability. Before 0.16.0 these were reachable whatever the tool set said.

Prompts (4)

MCP Prompts give AI clients guided workflows for common tasks:

Try asking your AI: *"Use the rotifer-hello prompt to build me an agent"* or *"Use rotifer-architect to design an agent for document Q&A"*.

Architecture

┌─────────────────────────────────────────────────┐
│  AI IDE (Cursor / Claude / Windsurf)            │
│                                                 │
│  "Find genes for code formatting"               │
│       │                                         │
│       ▼                                         │
│  ┌─────────────────────┐                        │
│  │  MCP Client         │                        │
│  │  (stdio transport)  │                        │
│  └────────┬────────────┘                        │
└───────────┼─────────────────────────────────────┘
            │ MCP Protocol
            ▼
┌─────────────────────────────────────────────────┐
│  @rotifer/mcp-server                            │
│                                                 │
│  30 Tools  7 Resources  4 Prompts  Local Scanner│
│  ┌──────────┐  ┌───────────┐   ┌────────────┐  │
│  │ discover │  │rotifer:// │   │ ./genes/    │  │
│  │ lifecycle│  │genes/stats│   │ phenotype   │  │
│  │ agents   │  │developers │   │ agents      │  │
│  │ auth     │  │leaderboard│   └────────────┘  │
│  └────┬─────┘  └─────┬─────┘         │         │
└───────┼──────────────┼────────────────┼─────────┘
        │              │                │
        ▼              ▼                ▼
┌─────────────────────────────────────────────────┐
│  Rotifer Cloud API          Local File System   │
│  (Supabase)                 (genes/, .rotifer/) │
└─────────────────────────────────────────────────┘

Configuration

Zero-config by default — connects to the public Rotifer Cloud API.

To use a custom endpoint, create `~/.rotifer/cloud.json`:

{
  "endpoint": "https://your-supabase-instance.supabase.co",
  "anonKey": "your-anon-key"
}

Or set environment variables:

ROTIFER_CLOUD_ENDPOINT=https://your-instance.supabase.co
ROTIFER_CLOUD_ANON_KEY=your-anon-key

Choosing which tools to expose

All thirty-one tools are available by default. `ROTIFER_MCP_TOOLS` narrows that

to what a given integration actually needs — useful when the server is attached

to an assistant that should not be able to publish or log in on your behalf:

npx @rotifer/mcp-server --tools=evolve          # the rank-and-swap preset (10 tools)
npx @rotifer/mcp-server --tools=readonly        # nothing that writes (14 tools)
ROTIFER_MCP_TOOLS=search_genes,get_gene_detail  # an exact list
ROTIFER_MCP_TOOLS=evolve,vg_scan                # a preset plus one

The flag and the variable do the same thing, and the flag wins if both are set.

Both exist because callers differ in what they can reach: a shell user sets the

variable, while something launching this server from a manifest controls only

the command line.

A declared set covers the whole surface, not just `tools/list`. Tools outside it

are refused when called by name; resources that duplicate an

excluded tool are dropped from the listing and refused when read; and the

sandbox escape hatches below stay off unless separately declared. A restriction

with an unlisted way around it is not a restriction.

Tools outside the set disappear from `listTools` and are refused if called

anyway. The refusal says how to add the tool back and, where one exists, the

`rotifer` CLI command that does the same job — so a narrowed set is a boundary

you can see and cross deliberately, not a dead end.

Leave it unset and nothing changes.

Switching off the sandbox

`agent_run` and `run_gene` take `no_sandbox`, and `run_gene` also takes

`trust_unsigned` — options that run Gene code as plain Node.js instead of inside

the WASM sandbox. Narrowing the tool set would mean little if a tool inside the

narrowed set could still do that, so these are refused unless declared at

launch:

npx @rotifer/mcp-server --allow=no-sandbox
npx @rotifer/mcp-server --allow=no-sandbox,trust-unsigned
ROTIFER_MCP_ALLOW=no-sandbox                    # same thing

Nothing is removed. The option moves from "any caller can set it" to "someone

declared it at launch", and you can always do it yourself:

rotifer agent run  --no-sandbox
rotifer run  --trust-unsigned

What changes is that an assistant can no longer decide to unsandbox on its own.

Passing `no_sandbox: false` is asking for the safe behaviour and is never

refused.

Undoing an install

`install_gene` with `force` used to overwrite a Gene with no way back. It now

moves the old copy into `/.snapshots/` first, and `rollback_gene` puts it

back:

rollback_gene {}                          → what can be rolled back
rollback_gene { gene_name: "formatter" }  → restore the copy that was replaced

One snapshot per Gene: the next overwrite of that Gene supersedes it, and a

rollback consumes it. This undoes the last upgrade rather than keeping a

history — `list_gene_versions` already answers what versions exist upstream.

Usage reporting

When you are signed in, each tool call reports a usage record to Rotifer

Cloud: the tool's name, the Gene id it acted on, whether it succeeded, how long

it took, and your user id. That is what `get_mcp_stats` reads back. Running a

Gene also records the invocation, which the protocol's anti-manipulation

metrics depend on.

It does not send the arguments you pass, the contents of any file, your

environment variables, or your local configuration.

Signed out, no usage record is sent. One request does go out either way:

installing a Gene bumps that Gene's public install counter. It carries the Gene

id and nothing else — no user id, no session, no arguments — and it is how the

Arena counts installs. Until 0.15.1 nothing stopped it, and this section said

"signed out, nothing is reported", which was not true of an install.

`ROTIFER_TELEMETRY=0` now stops all three:

ROTIFER_TELEMETRY=0    # also accepts false / off

The three are `logMcpCall`, `logGeneInvocation` and the `track_download` call

inside `installGene`, all in `src/cloud.ts` — short enough to

read in full. Nothing else here reports anything on its own: every other

outbound call in this server is a tool you invoked doing its job — a query, a

publish, a sign-in — plus the WASM artifact download and one npm version check

per day.

Requirements

• Node.js >= 20

Pair with the CLI

This MCP server works best alongside the Rotifer CLI. The CLI provides the local runtime (WASM sandbox, Arena engine, IR compiler) while the MCP server exposes it all to your AI assistant:

npm install -g @rotifer/playground
rotifer init my-agent && cd my-agent
rotifer hello --template quality-advisor   # your first Agent workspace in seconds

Links

• Rotifer Protocol — Main site
• MCP Setup Guide — Step-by-step setup
• Gene Marketplace — Browse and discover Genes
• CLI Playground — Build and test Genes locally
• Protocol Specification — Formal spec

License

Apache-2.0