@rotifer/mcp-server

Build, compose, and run AI agents — directly from your IDE.

Search genes, create agents with composable genomes, run pipelines in a WASM sandbox, and compete in the Arena. Zero config. Works with Cursor, Claude Desktop, Windsurf, and any MCP-compatible client.

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.

Related MCP server: aiskillstore

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                            │
│                                                 │
│  31 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

The login MCP tool always signs in to the configured endpoint and refuses an endpoint argument: an assistant can be steered by what it reads, and sign-in sends credentials to that address. To sign in to another instance yourself, run rotifer-mcp-server login --endpoint <url>, which accepts only http:// or https:// addresses.

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

A name that is neither a preset nor a tool here is ignored, with a note on stderr. If none of the names are, the server does not start: it lists the presets and exits with code 2, rather than running with no tools at all.

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 <name> --no-sandbox
rotifer run <gene> --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 <genes>/.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.

Keeping the server up to date

The server has always told you when it was behind — a line on stderr at startup, once a day. self-update is the other half:

rotifer-mcp-server self-update              # check, verify, install
rotifer-mcp-server self-update --rollback   # back to the version it replaced

It refuses any version npm has no provenance attestation for — this package publishes from CI with --provenance, so an unattested build is not one this project released.

Two things worth knowing:

• A running server keeps serving the old code. Installing replaces files on disk; it does not replace the process your editor is already talking to. Restart your MCP host afterwards.

• If you launch through npx, there is nothing to update. An unpinned npx @rotifer/mcp-server re-resolves the latest published version on every run, so self-update says so and stops rather than installing a global copy that would shadow it.

This is a command you run, not a tool the model can call. Updating means a global install, and a tool could not even report the result honestly — the model would say "updated" while still being served by the old process.

Serving over HTTP

The server normally talks over stdio to the MCP host that launched it. To expose it over Streamable HTTP instead:

rotifer-mcp-server serve                      # http://127.0.0.1:3000/mcp
rotifer-mcp-server serve --port 8080

# Reachable from other machines: needs a list of names and an access token
openssl rand -hex 32 > mcp-token
chmod 600 mcp-token
rotifer-mcp-server serve --host 0.0.0.0 --allowed-hosts mcp.example.com --token-file mcp-token

• It listens on 127.0.0.1 unless you pass --host. Its tools act with your signed-in Rotifer account, so it is not reachable from other machines by default. If you pass a non-loopback --host, the server says so on stderr when it starts. Earlier versions listened on every interface.

• A non-loopback --host needs --allowed-hosts. List the host names or IP addresses clients will use, separated by commas, with no scheme, port, path or wildcard. Without the list, serve exits with status 2. Earlier versions started anyway.

• A non-loopback --host also needs an access token. Pass --token-file <path> or set ROTIFER_MCP_HTTP_TOKEN, not both. A line break at the end of the file is ignored. The token is not accepted as a command-line value, because other programs on the machine can read those. Without a token, serve exits with status 2. On loopback a token is optional, and is enforced if you set one. Earlier versions had no token.

• Every path except /health only answers requests addressed to a name it knows. The Host header, and the Origin header when a browser sends one, must be loopback or an entry in --allowed-hosts; anything else gets 403. Listening on loopback alone does not stop a web page from reaching the server through DNS rebinding.

• With a token set, every path except /health also needs Authorization: Bearer <token>. A missing or wrong token gets 401. CORS preflight (OPTIONS) is exempt, because browsers cannot attach the header to it; it still has to pass the Host and Origin check, and it never reaches a tool.

• --allowed-hosts and the token do different jobs, and a request must pass both. --allowed-hosts decides which names the server may be addressed by, which stops DNS rebinding. It says nothing about who is calling. The token decides who may call.

• Everyone holding the token acts as the account signed in on the server. There are no per-user tokens or permission levels. To revoke access, change the token and restart the server.

• The server speaks plain HTTP. The token travels with every request, so a server reachable from other machines belongs behind an HTTPS reverse proxy or tunnel.

• login and logout are not available over HTTP. They are not listed, and calling them returns an error, because they act on the credentials of the machine running the server. On that machine, run rotifer-mcp-server login or rotifer-mcp-server logout.

• Request bodies are capped at 256 KiB. A larger request is answered 413 with a JSON-RPC error before it is parsed. MCP messages are far smaller than this; the cap exists because the SDK's default (4 MiB) is the bound GHSA-46jr-4wx8-v453 describes, where a single request can exhaust the server's memory.

• GET /health answers {"status":"ok","transport":"streamable-http"} for liveness checks.

To send the token from a client, each of these reads it at connection time, so it stays out of the configuration file.

Claude Code, in .mcp.json:

{
  "mcpServers": {
    "rotifer": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer ${ROTIFER_MCP_HTTP_TOKEN}" }
    }
  }
}

Cursor, in mcp.json:

{
  "mcpServers": {
    "rotifer": {
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer ${env:ROTIFER_MCP_HTTP_TOKEN}" }
    }
  }
}

VS Code, in mcp.json:

{
  "inputs": [
    { "type": "promptString", "id": "rotifer-token", "description": "Rotifer MCP access token", "password": true }
  ],
  "servers": {
    "rotifer": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer ${input:rotifer-token}" }
    }
  }
}

Claude Desktop uses stdio by default.

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