Connect your agent

Quick start

The simplest way to connect, paste the URL into your agent's MCP config. Authentication happens automatically via OAuth when your agent first connects.

Claude Code

claude mcp add --transport http --scope user nodeon https://www.nodeon.app/api/mcp

Cursor

Create or edit .cursor/mcp.json:

{
  "mcpServers": {
    "nodeon": {
      "url": "https://www.nodeon.app/api/mcp"
    }
  }
}

Codex (OpenAI)

Run in your terminal, then sign in when the browser opens:

codex mcp add nodeon --url https://www.nodeon.app/api/mcp
codex mcp login nodeon

Or add it to ~/.codex/config.toml by hand:

[mcp_servers.nodeon]
url = "https://www.nodeon.app/api/mcp"

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json, then hit Refresh in Cascade's MCP panel. Windsurf uses serverUrl, not url:

{
  "mcpServers": {
    "nodeon": {
      "serverUrl": "https://www.nodeon.app/api/mcp"
    }
  }
}

How OAuth works

Nodeon implements the MCP authorization specification (OAuth 2.1 with PKCE). The flow is:

1. Your agent sends a request to /api/mcp without a token.
2. The server responds with 401 Unauthorized and a WWW-Authenticate header pointing to the resource metadata.
3. Your agent discovers the authorization server at /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server.
4. Your agent dynamically registers itself (POST /oauth/register), no manual setup needed.
5. A browser window opens for you to sign in and authorize access.
6. Your agent exchanges the authorization code for tokens (POST /oauth/token) using PKCE.
7. Access tokens are JWTs with audience binding. Refresh tokens rotate automatically.

Endpoints

• GET /.well-known/oauth-protected-resource Protected Resource Metadata (RFC 9728)
• GET /.well-known/oauth-authorization-server Authorization Server Metadata (RFC 8414)
• POST /oauth/register: Dynamic Client Registration (RFC 7591)
• GET /oauth/authorize: Authorization endpoint (PKCE, S256)
• POST /oauth/token: Token endpoint (authorization_code + refresh_token grants)

Available tools

Once connected, your agent can call these tools:

• list_projects: list your projects
• get_next_task: get the next unblocked node with its scoped context
• get_project_graph: pull the whole node graph at once: nodes, statuses, edges, build order
• get_node: re-read a single node's spec and its dependency links
• mark_task_complete: mark a node as done; refused while its dependencies are still open (force flag to override, logged)
• add_subtask: add a discovered task to the graph, including a node with your own custom type name
• batch_add_subtasks: create many tasks and their dependencies in a single call
• update_node: edit a node's title or spec after creation
• delete_node: remove junk nodes, placeholders, tests, duplicates
• create_project: start a new project without leaving the chat
• apply_template: seed an empty project with a starter plan (SaaS MVP, landing page or mobile app)
• rename_project: rename a project; its graph, node ids and map link stay the same
• delete_project: delete an entire project, every node with it, after confirming the project's name
• add_dependency: connect two nodes with a dependency
• remove_dependency: unlink two nodes
• flag_blocker: flag a node as blocked with a reason
• unblock_task / reopen_task: return a node to the queue
• disconnect: disconnect this assistant from Nodeon; the connection stops working until you re-authorize

How the MCP connection works

Nodeon uses the Streamable HTTP transport. Every request is a JSON-RPC 2.0 message sent as an HTTP POST to /api/mcp. The server is stateless, no session tracking, no WebSocket, no SSE stream to maintain.

Each request carries its own OAuth token and protocol version. If the server restarts, the next request works without reconnection.

Typical workflow

1. Your agent calls list_projects to see what's available.
2. It calls get_next_task with a project ID. Nodeon returns the highest-priority unblocked node, along with its dependencies, dependents, and full spec.
3. The agent builds that task.
4. It calls mark_task_complete to update the graph.
5. It calls get_next_task again. The next unblocked node is now returned.
6. If the agent discovers new work, it calls add_subtask. If it hits a wall, it calls flag_blocker.

Repeat until all nodes are done or blocked.

Local development

If you're running Nodeon locally (npm run dev), use http://localhost:3000/api/mcp as the URL. OAuth works over localhost without HTTPS.

claude mcp add --transport http --scope user nodeon http://localhost:3000/api/mcp

Troubleshooting

401 Unauthorized

Your token is missing, expired, or wrong. Your agent should handle re-authentication automatically through OAuth. If the error persists, remove the Nodeon MCP server from your client and add it again.

Connection refused

Check that the URL is correct and the server is running. For local development, make sure npm run dev is running.

Tools not appearing

Some agents cache the tool list. Restart the agent or clear its MCP cache. In Claude Code, run claude mcp reset.

Graph contains a cycle

If get_next_task returns a cycle error, your dependency graph has a loop. Open the canvas and remove the circular edge.