MCP Server Setup

The Rotifer MCP Server lets any MCP-compatible Agent access the entire Gene ecosystem programmatically. Supports Claude Desktop, Cursor, VS Code, Windsurf, JetBrains, Zed, Cline, Continue, and more.

Quick Setup

Most IDEs use the standard mcpServers format. Add the following to your IDE’s MCP configuration:

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

VS Code / GitHub Copilot and Zed use different config formats — see IDE-specific instructions below.

IDE Setup

Claude Desktop

Edit the config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Restart Claude Desktop after saving.

Cursor

Create .cursor/mcp.json in your project root, or edit the global config at ~/.cursor/mcp.json:

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

VS Code / GitHub Copilot

VS Code uses a servers field (not mcpServers) and requires a type field. Create .vscode/mcp.json in your project root:

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

You can also add servers via the Command Palette: MCP: Add Server. GitHub Copilot in VS Code uses the same config.

Windsurf

Edit the config file:

• macOS / Linux: ~/.codeium/windsurf/mcp_config.json
• Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

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

JetBrains (IntelliJ IDEA / WebStorm / PyCharm etc.)

Open Settings → Tools → AI Assistant → Model Context Protocol (MCP), click Add (+), select STDIO:

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

Requires IntelliJ 2025.1 or later. Supports STDIO, HTTP, and SSE transports.

Zed

Zed uses the context_servers format. Edit Settings (Cmd+,) or use the Command Palette agent: open settings:

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

Cline

Cline uses its own config file cline_mcp_settings.json. Open the Cline sidebar in VS Code → MCP Servers → Add:

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

Continue

Add the MCP Server to .continue/config.yaml:

mcpServers:
  - name: rotifer
    command: npx
    args:
      - "@rotifer/mcp-server"

Continue also supports importing Claude Desktop / Cursor JSON configs. MCP is available in Agent mode only.

Authentication (Optional)

The MCP Server runs in anonymous mode by default, allowing you to search and browse public Genes. To use Cloud features (publish Genes, manage your profile, etc.), log in first:

npx @rotifer/mcp-server login

Both GitHub and GitLab OAuth are supported. To specify a provider:

npx @rotifer/mcp-server login --provider github

To log out:

npx @rotifer/mcp-server logout

Credentials are stored in ~/.rotifer/credentials.json and shared with the @rotifer/playground CLI.

Available Tools

Cloud Query Tools

These tools query the Rotifer Cloud Registry. No authentication required.

Tool	Description	Key Parameters
search_genes	Search the Gene ecosystem by name, domain, or fidelity	query, domain, fidelity, sort, page, per_page
get_gene_detail	Get detailed Gene information including phenotype and fitness	gene_id (Gene UUID, name, or content hash), content_hash (optional alternative)
get_arena_rankings	View domain Arena rankings sorted by F(g)	domain, page, per_page
compare_genes	Side-by-side fitness comparison of 2-5 Genes	gene_ids (array of UUIDs, required)
get_gene_stats	Download statistics for a Gene (total, 7d, 30d, 90d)	gene_id (required)
get_leaderboard	Creator reputation leaderboard	limit (default 20, max 100)
get_developer_profile	Get a creator’s profile and reputation by username	username (required)
list_gene_versions	Version history chain of a Gene by owner and name	owner, gene_name (both required)
get_gene_reputation	Detailed reputation breakdown (Arena, Usage, Stability)	gene_id (required)
suggest_domain	Suggest matching domains from the domain registry	description (required)

Local Workspace Tools

These tools operate on Genes and Agents in your local Agent workspace directory.

Tool	Description	Key Parameters
list_local_genes	Scan locally installed Genes in the Agent workspace	project_root, domain, fidelity
list_local_agents	List Agents registered in the local workspace	project_root, state
init_gene	Initialize a new Gene project with phenotype.json template	gene_name (required), fidelity, domain, no_genesis, project_root
scan_genes	Scan source files for candidate gene functions or SKILL.md	path, skills, skills_path, project_root
wrap_gene	Wrap a function or SKILL.md as a Rotifer Gene	gene_name (required), domain, fidelity, from_skill, from_clawhub, project_root
compile_gene	Compile a Gene to WASM	gene_name (required), check, wasm_path, lang, project_root
run_gene	Execute a local Gene	gene_name (required), input, verbose, no_sandbox, trust_unsigned, project_root
test_gene	Test a Gene in the sandbox (schema, I/O, compilation)	gene_name (required), verbose, compliance, project_root
install_gene	Install a Gene from Cloud Registry into the local Agent workspace	gene_id (required), force, project_root
vg_scan	V(g) security scan — static analysis for Gene/Skill code safety (grade A/B/C/D/?)	path, gene_id, all, project_root

Cloud Write Tools

These tools modify data in Rotifer Cloud. Authentication required (run login first).

Tool	Description	Key Parameters
publish_gene	Publish a Gene to Rotifer Cloud	gene_name, all, description, changelog, skip_arena, skip_security, project_root
arena_submit	Submit a Gene to the Arena with 5-dimensional fitness scores	gene_id, fitness_value, safety_score, success_rate, latency_score, resource_efficiency (all required)
create_agent	Create an Agent by composing local Genes	agent_name (required), gene_ids (required, ≥1), composition (Seq/Par/Cond/Try/TryPool), domain (metadata only), strategy, par_merge, project_root
agent_run	Run a local Agent by name	agent_name (required), input, verbose, no_sandbox, project_root

Authentication & Meta Tools

Tool	Description	Key Parameters
auth_status	Check current authentication status (username, provider, expiry)	—
login	Log in to Rotifer Cloud via OAuth (opens browser)	provider (github or gitlab, default: github), endpoint
logout	Log out and clear locally saved credentials	—
get_mcp_stats	MCP Server call analytics (calls, latency, top tools)	days (default 7). Requires auth.
get_my_reputation	Current logged-in creator’s reputation and stats	— . Requires auth.

MCP Resources

The MCP Server also provides Resource templates that Agents can read via URI:

URI Template	Description
rotifer://genes/{gene_id}/stats	Gene download statistics
rotifer://genes/{gene_id}	Full Gene metadata and phenotype
rotifer://developers/{username}	Creator profile and reputation
rotifer://leaderboard	Top creators by reputation score
rotifer://local/genes	All Genes installed in the current Agent workspace
rotifer://local/agents	All Agents registered in the current Agent workspace
rotifer://version	MCP Server version and update availability

Example Usage

Once configured, your Agent can:

"Search for web scraping genes"
→ search_genes({ query: "web scraping" })

"Which search gene has the highest fitness?"
→ get_arena_rankings({ domain: "search.web" })

"Compare these two genes"
→ compare_genes({ gene_ids: ["uuid1", "uuid2"] })

"Who has the highest reputation?"
→ get_leaderboard({ limit: 10 })

"What genes are installed locally?"
→ list_local_genes({})

"Create a new gene for text summarization"
→ init_gene({ gene_name: "summarize.text.my-v1", fidelity: "Wrapped" })

"Publish my gene to the cloud"
→ publish_gene({ gene_name: "summarize.text.my-v1" })

"Security scan my gene"
→ vg_scan({ path: "genes/summarize.text.my-v1", gene_id: "summarize.text.my-v1" })

"Check my auth status"
→ auth_status()

"Show version history for a gene"
→ list_gene_versions({ owner: "alice", gene_name: "search.web.google-v2" })

CLI ↔ MCP Mapping

Every MCP tool maps to one or more CLI commands (and vice versa). Use this table when switching between CLI and MCP workflows.

CLI Command	MCP Tool	Notes
rotifer search	search_genes
rotifer info <gene-ref>	get_gene_detail	CLI uses info, MCP uses get_gene_detail
rotifer arena list	get_arena_rankings
rotifer compare	compare_genes
rotifer stats	get_gene_stats
rotifer reputation --leaderboard	get_leaderboard
rotifer reputation [gene-ref]	get_gene_reputation
rotifer reputation --mine	get_my_reputation	Requires auth
rotifer whoami	auth_status	CLI whoami = MCP auth_status
rotifer versions	list_gene_versions
rotifer list	list_local_genes
rotifer agent list	list_local_agents
rotifer init	init_gene
rotifer scan	scan_genes
rotifer wrap	wrap_gene
rotifer compile	compile_gene
rotifer run	run_gene
rotifer test	test_gene
rotifer install	install_gene
rotifer publish	publish_gene	Requires auth
rotifer arena submit	arena_submit	Requires auth
rotifer agent create	create_agent
rotifer agent run	agent_run
rotifer login	login
rotifer logout	logout
rotifer arena watch	—	Interactive; no MCP equivalent
rotifer network *	—	P2P stubs; no MCP equivalent
rotifer vg	vg_scan	Returns JSON report with grade + findings
—	get_mcp_stats	MCP-only: call analytics
—	suggest_domain	MCP-only: domain suggestion
—	get_developer_profile	MCP-only (CLI uses reputation)

OpenClaw Integration

If you use OpenClaw, Rotifer works as an MCP-based Skill. Install manually:

git clone https://github.com/rotifer-protocol/rotifer-self-evolving-agent.git \
  ~/.openclaw/workspace/skills/rotifer-self-evolving-agent

Then restart OpenClaw. Use /rotifer to access all Gene ecosystem tools.

WebMCP

WebMCP (Web Model Context Protocol) allows browser-based AI Agents to discover and invoke Rotifer tools directly from web pages — no server configuration needed.

How it works

Rotifer’s homepage and rotifer.ai embed declarative <form> tags that expose tools to any WebMCP-compatible browser Agent:

<form hidden toolname="search_docs"
      tooldescription="Search Rotifer Protocol documentation">
  <input name="query" type="text"
         toolparamdescription="Search keywords" />
</form>

When an Agent visits rotifer.dev or rotifer.ai, it automatically discovers these tools and can call them without any manual setup.

Available WebMCP Tools

rotifer.ai (14 tools: 10 read-only + 4 write):

Tool	Description	Executable
search_genes	Search the Gene ecosystem	Yes
get_gene_detail	Get Gene details by name or UUID	Yes (with name→UUID resolution)
get_arena_rankings	View Arena rankings	Yes
compare_genes	Compare 2-5 Genes side-by-side	Yes
get_gene_stats	Get download and usage stats	Yes
get_leaderboard	Top creators by reputation	Yes
get_developer_profile	Creator profile and Genes	Yes
list_gene_versions	Version history for a Gene	Yes
get_gene_reputation	Reputation breakdown for a Gene	Yes
get_rotifer_capabilities	List all tools and their availability	Yes (meta-tool)
set_gene_visibility	Set Gene as published/visible (WebMCP-only)	Yes (requires login)
request_arena_evaluation	Request server-side Arena evaluation (WebMCP-only)	Yes (requires login)
create_gene	Create Gene entry in registry (WebMCP-only)	Yes (requires login)
update_gene_metadata	Update Gene metadata (WebMCP-only)	Yes (requires login)

Naming note: set_gene_visibility and request_arena_evaluation are WebMCP-only tools, deliberately named differently from the MCP tools publish_gene and arena_submit. The MCP versions run full local-to-cloud pipelines, while the WebMCP versions perform simpler browser-side operations. See ADR-198 for the semantic equivalence constraint.

rotifer.dev (3 tools):

Tool	Description	Executable
search_docs	Search protocol documentation	Discovery only
get_mcp_config	Get MCP Server config snippet	Yes
suggest_domain	Suggest a Gene domain from description	Yes

Note: rotifer.ai WebMCP tools accept gene names (e.g. search.web.google-v2) in addition to UUIDs, and automatically resolve them to UUIDs before querying the Cloud API.

Browser Support

WebMCP is a W3C Community Group specification with Early Preview in Chrome 146 (February 2026). Supported by Agents that implement the Web MCP specification, including browser extensions and Agent frameworks with web browsing capabilities.

Environment Variables

Variable	Description	Default
ROTIFER_CLOUD_ENDPOINT	Cloud API endpoint	https://cloud.rotifer.dev
ROTIFER_CLOUD_ANON_KEY	API key	(built-in)

Requirements

• Node.js >= 20
• Internet access (to reach Rotifer Cloud API)

Troubleshooting

“Tool not found” error: Ensure npx is in your PATH and Node.js >= 20 is installed.

Connection timeout: Check your internet connection. The MCP Server connects to cloud.rotifer.dev.

No results returned: The Gene ecosystem is in alpha. Try broader search terms or check available domains with get_arena_rankings({}).