neo-mcp 0.4.25

MCP server for the Neo AI/ML backend — submit tasks, poll status, read output

neo-mcp

Python MCP server for Neo — submit AI/ML tasks, poll status, read output, and control task lifecycle from any AI editor.

The server runs locally over stdio. On first task submission it auto-starts the npm daemon (npx neo-mcp-daemon) to handle local file execution. A Python daemon fallback is built in for environments where Node.js is unavailable.

Get your API key at app.heyneo.so → Settings → API Keys.

---

Install

pip install neo-mcp

Requires Python 3.11+.

Tip: use pipx install neo-mcp to install in an isolated environment and avoid conflicts with your project's virtualenv.

---

Connecting to editors

All editors below run neo-mcp as a stdio subprocess. Replace sk-v1-YOUR_KEY with your actual key.

---

Claude Code

claude mcp add --scope user neo \
  -e NEO_SECRET_KEY=sk-v1-YOUR_KEY \
  -- neo-mcp

Open a new Claude Code session after running this command. Neo tools load at session start.

Scope options: --scope user (global, recommended) · --scope project (writes .mcp.json in current repo) · --scope local (this machine only)

Verify the server registered correctly:

claude mcp list

---

Cursor

Edit ~/.cursor/mcp.json (create if it doesn't exist):

{
  "mcpServers": {
    "neo": {
      "command": "neo-mcp",
      "env": {
        "NEO_SECRET_KEY": "sk-v1-YOUR_KEY"
      }
    }
  }
}

Restart Cursor after editing.

---

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "neo": {
      "command": "neo-mcp",
      "env": {
        "NEO_SECRET_KEY": "sk-v1-YOUR_KEY"
      }
    }
  }
}

Restart Windsurf after editing.

---

VS Code (GitHub Copilot)

Requires VS Code 1.99+. Edit .vscode/mcp.json in your workspace root:

{
  "servers": {
    "neo": {
      "type": "stdio",
      "command": "neo-mcp",
      "env": {
        "NEO_SECRET_KEY": "sk-v1-YOUR_KEY"
      }
    }
  }
}

---

Zed

Edit ~/.config/zed/settings.json:

{
  "context_servers": {
    "neo": {
      "source": "custom",
      "command": {
        "path": "neo-mcp",
        "args": [],
        "env": {
          "NEO_SECRET_KEY": "sk-v1-YOUR_KEY"
        }
      }
    }
  }
}

---

Continue.dev

Edit ~/.continue/config.json:

{
  "mcpServers": [
    {
      "name": "neo",
      "transport": {
        "type": "stdio",
        "command": "neo-mcp",
        "env": {
          "NEO_SECRET_KEY": "sk-v1-YOUR_KEY"
        }
      }
    }
  ]
}

---

OpenAI Codex CLI

Edit ~/.codex/config.json:

{
  "mcpServers": {
    "neo": {
      "command": "neo-mcp",
      "env": {
        "NEO_SECRET_KEY": "sk-v1-YOUR_KEY"
      }
    }
  }
}

---

Tools

Tool	Description
neo_submit_task	Submit an AI/ML task. Returns thread_id immediately.
neo_list_tasks	List running and recent tasks — reconnects pollers automatically.
neo_task_status	Check status: RUNNING / COMPLETED / WAITING_FOR_FEEDBACK / PAUSED / TERMINATED.
neo_get_messages	Read full task output when COMPLETED. Capped at ~20 000 tokens.
neo_send_feedback	Reply when Neo asks a question (WAITING_FOR_FEEDBACK).
neo_pause_task	Pause a running task.
neo_resume_task	Resume a paused task.
neo_stop_task	Stop and clean up a task permanently.

---

Daemon management

The MCP server auto-starts the npm daemon on first task submission. To start it manually:

# npm daemon (recommended — Node.js required)
NEO_SECRET_KEY=sk-v1-YOUR_KEY npx --yes neo-mcp-daemon /path/to/workspace &

# Python daemon (fallback — no Node.js needed)
NEO_SECRET_KEY=sk-v1-YOUR_KEY neo-mcp daemon

Check daemon status:

neo-mcp status
neo-mcp doctor
neo-mcp logs --source daemon --lines 50

---

Setup wizard

Auto-configure all supported editors in one step:

neo-mcp setup

Flags:

Flag	Description
--secret-key KEY	Skip interactive key prompt
--editor EDITORS	Comma-separated: claude,cursor,windsurf,zed,vscode,continue,codex
--scope SCOPE	Claude Code scope: user (default), project, or local
--no-backup	Skip .bak backups when overwriting existing configs

Example:

neo-mcp setup --secret-key sk-v1-... --editor claude,cursor

---

Environment variables

Variable	Required	Description
NEO_SECRET_KEY	Yes	Your Neo API key (sk-v1-...) from app.heyneo.so
NEO_DEPLOYMENT_ID	No	Pin a specific deployment UUID (auto-generated and persisted by default)
NEO_WORKSPACE_DIR	No	Override working directory (useful in Docker)
NEO_READ_ONLY	No	true — expose only status/message tools, disable submit/stop/pause

---

Troubleshooting

Symptom	Fix
neo-mcp: command not found	Re-run pip install neo-mcp; check which neo-mcp and verify your PATH
Tools don't appear after registering	Open a new session — MCP tools load at session start, not mid-session
Invalid API key (401)	Re-check your key at app.heyneo.so → Settings → API Keys
Trial or quota ended (403)	Top up at the Neo dashboard
Task submitted but no files written	Daemon failed to start — run NEO_SECRET_KEY=sk-v1-... npx --yes neo-mcp-daemon /workspace & manually
Status stuck on RUNNING	Daemon stopped mid-task — restart it and call neo_task_status to check