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)

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

Windsurf

{
  "mcpServers": {
    "nodeon": {
      "url": "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
• mark_task_complete: mark a node as done
• add_subtask: add a discovered task to the graph
• add_dependency: connect two nodes with a dependency
• flag_blocker: flag a node as blocked with a reason

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_projectsto 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.