MCP

The Nocturnal MCP server lets Claude Code, Codex, Claude Desktop, Cursor, or any other MCP client do what you do in the dashboard: create and import projects, start agents and add to their conversations, create and edit plans, run scripts and processes, commit, file issues, and cut versions. It reaches every computer signed in to your account.

Connect

Nocturnal's MCP server lives at https://nocturnal.sh/mcp. Add it to your client by URL, then sign in with your Nocturnal account. There's nothing to install and no key to copy.

Claude (claude.ai, Claude Desktop, and the phone app): Settings → Connectors → Add custom connector, paste the URL, and connect.

Claude Code:

claude mcp add --transport http --scope user nocturnal https://nocturnal.sh/mcp

Then run /mcp, choose nocturnal, and Authenticate.

Codex:

codex mcp add nocturnal --url https://nocturnal.sh/mcp
codex mcp login nocturnal

ChatGPT, Cursor, and other clients: add a remote MCP server with the same URL.

Your client opens nocturnal.sh. Sign in the way you normally do, for example with Google, and choose Allow. The page names the app and where it sends you back to, so only allow a connection you started yourself. Your client keeps you signed in after that. To disconnect, remove the server from the client.

Choose a computer

Every tool takes an optional device: a computer's name, part of its name, or its id.

• Leave it out and the call goes to your only online computer.
• Several computers online? The tool replies with the list and asks which one, so the model can ask you or use the one you named ("on the Studio").
• nocturnal_devices lists your computers, which ones are online, and where calls go by default.

Calls travel through your account, the same way the dashboard and the phone app reach a computer, and usually answer in two to four seconds. That computer has to be awake with Nocturnal running. An offline computer is refused straight away instead of queueing.

What you can do

Every engine command is a tool, named with an underscore instead of the dot. agent.new is agent_new, agent.continue is agent_continue, plan.create is plan_create, and project.create is project_create. Each tool carries its own parameters and description, generated from the same catalog the CLI and the HTTP API use, so a client never sees a stale or missing tool.

Two tools belong to the server itself:

Things to ask for:

• "Start an agent on my-app to fix the header spacing."
• "Tell that agent to check the mobile layout too."
• "What's running on my MacBook?"
• "Create a plan for the billing rework on the Studio."

Tools that only read are described as read-only. Tools that need something physical, such as a window, a Finder dialog, or a log file, say so, and they act on whichever computer runs the call.

A remote, with your authority

The MCP server is a remote control, like the phone app. What you ask for happens as if you did it in the dashboard: an agent can start in Agent mode and build, and roadmap changes apply straight away. nocturnal_devices shows this as actingAs. Nothing is committed unless something asks for git_commit. Nocturnal never branches or commits on its own.

Run it on your computer instead

A local version runs through npx (Node.js 20 or later) and talks to the engine on the same computer directly, with no account round trip. Use it when you want a computer to reach its own engine without the cloud.

claude mcp add --scope user nocturnal -- npx -y --registry=https://nocturnal.sh/npm nocturnal-mcp@latest
codex mcp add nocturnal -- npx -y --registry=https://nocturnal.sh/npm nocturnal-mcp@latest

For clients that take a JSON config:

{
  "mcpServers": {
    "nocturnal": {
      "command": "npx",
      "args": [
        "-y",
        "--registry=https://nocturnal.sh/npm",
        "nocturnal-mcp@latest"
      ]
    }
  }
}

It uses the Nocturnal app's sign-in on that computer. On a computer without the app, run npx -y --registry=https://nocturnal.sh/npm nocturnal-mcp@latest login once, or ask your agent to use its nocturnal_sign_in tool. With the local version, a call without a device goes to that computer's own engine first, and NOCTURNAL_DEVICE pins a different default.

The local version knows when Nocturnal itself launched the run using it, such as a chat in the dashboard. Those calls count as an agent's: it can start Ask and Plan conversations but not a builder run, and its roadmap changes wait for your review. That stops an agent from starting agents nobody asked for.

If your model cannot run an MCP server, see Control Nocturnal from an agent for the CLI and HTTP routes to the same commands.