Skip to Content

Neo MCP

Your coding agent, running AI/ML engineering tasks

You already use Cursor, Claude Code, or Copilot to edit code and answer questions. AI/ML work often needs more: run a training job, optimize or fix an AI agent, compare model evals, iterate on a pipeline — work that takes multiple steps, not one chat reply.

Neo MCP plugs Neo into that chat via the Model Context Protocol. You ask your agent; the agent starts a Neo task; Neo plans, runs, and debugs in your environment and writes code, metrics, and reports into your repo. You review changes in the IDE like any other work.

Neo MCP workflow: you ask your coding agent in the editor, the agent calls Neo over MCP, Neo runs the AI/ML task, and outputs land in your repository

You → coding agent → Neo (via MCP) → runnable artifacts in your repo

Ask your agent to use Neo — for example:

Set up Neo MCPWhat is Neo?

Works with Cursor, Claude Code, VS Code Copilot, Windsurf, Zed, Continue, Codex CLI, and other MCP editors.

Set up Neo MCP

Get your API key

  1. Open API keys in the Neo dashboard (sign in if prompted).
  2. Create a key and copy it. Keys look like sk-v1-… — treat them like secrets and do not commit them to git.

You will paste this value wherever the examples use sk-v1-YOUR_KEY.

Install

Python 3.11+:

pip install neo-mcp

If pip install neo-mcp fails with error: externally-managed-environment, run:

python3 -m pip install --user --break-system-packages neo-mcp

Installs to ~/.local/ without sudo.

Editor configuration

Replace sk-v1-YOUR_KEY with your real key in the snippet for your editor.

Claude Code configures MCP through the claude mcp CLI (run these in your system terminal, not inside a chat).

1. Register Neo

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

2. Confirm it’s connected

claude mcp list

You should see neo with a green checkmark.

MCP tools

ToolWhat it does
neo_submit_taskStart a Neo task; returns a thread_id. Optional wait_for_completion blocks until finished.
neo_task_statusPoll status (RUNNING, COMPLETED, WAITING_FOR_FEEDBACK, etc.).
neo_get_messagesRead the task transcript after completion (large output may be capped).
neo_list_tasksList recent or active tasks (e.g. after reopening the editor).
neo_send_feedbackReply when Neo is waiting for input (WAITING_FOR_FEEDBACK).
neo_pause_task / neo_resume_taskPause or resume a task.
neo_stop_taskStop and tear down a task.
neo_add_integrationStore a provider key (GitHub, HuggingFace, Anthropic, OpenRouter, or any custom secret) on your machine so Neo can use it in tasks.
neo_list_integrationsList configured integrations (provider names only — never prints the secret).
neo_test_integrationCall the provider’s API once to confirm the stored key is still valid.
neo_remove_integrationDelete a stored key and its file (or keyring entry).

Typical flow: submit → poll status until COMPLETED or feedback → get messages (or use wait_for_completion on submit to skip polling).

Integrations

Give Neo access to external services — GitHub, HuggingFace, Anthropic, OpenRouter, or any custom secret — by storing API keys on your machine once. Neo injects them as environment variables every time it runs a task, so your scripts, CLIs, and libraries just work. Keys never leave your machine.

Adding a key

Just tell Neo in plain English — from any MCP-connected editor:

“Add my Anthropic key sk-ant-... to Neo.”

“Store my GitHub PAT ghp_... so Neo can push to my repos.”

“Save my HuggingFace token hf_... for downloading models.”

Neo calls neo_add_integration behind the scenes. You only need to do this once per provider — the key is stored locally and reused across every future task.

ProviderCredentialWhat Neo can do with it
githubPersonal Access Token (ghp_...)Clone private repos, push, open PRs
huggingfaceToken (hf_...)Download private models and datasets
anthropicAPI key (sk-ant-...)Run Claude models inside your tasks
openrouterAPI key (sk-or-...)Route through any model OpenRouter supports

You can also store any custom secret the same way — use any provider name and Neo will save it and expose it to tasks.

Where keys are stored

Keys are saved to a small file on your machine at ~/.neo/integrations/<provider>.env. The file is owner-read-only — no other user on your computer can access it. This is the same way tools like gh, aws, and huggingface-cli store their tokens.

For GitHub and HuggingFace, Neo also writes the token where the official CLI expects it (~/.git-credentials and ~/.cache/huggingface/token), so commands like git clone and huggingface-cli just work on their own — without Neo running.

  • Works everywhere: Mac, Linux, Docker, servers, CI.
  • Nothing extra to install.

Tip: turn on full-disk encryption (FileVault on macOS, BitLocker on Windows, LUKS on Linux) for an extra layer of protection when your machine is powered off or stolen.

How Neo uses your keys

When Neo runs a task, it reads your configured keys and sets them as environment variables on each child process:

VariableProvider
ANTHROPIC_API_KEYanthropic
OPENROUTER_API_KEYopenrouter
HF_TOKEN / HUGGING_FACE_HUB_TOKENhuggingface
GITHUB_TOKEN / GH_TOKENgithub

Any script, CLI, or library that reads these env vars works out of the box — no per-task configuration needed.

Managing integrations

neo_list_integrations              # shows configured providers (names only, never the key)
neo_test_integration anthropic     # calls the provider's API to confirm the key is valid
neo_remove_integration anthropic   # deletes the stored key and its file or keyring entry

Security