Connect AI Agents with MCP

Nodeable's MCP server lets a compatible external AI client discover workspace, project, and branch context; read graph and wiki content; export models; and use supported preview/apply workflows.

The MCP server's AI tools run structured operations (execute_ai_operation and stream_ai_operation); in-app chat and conversation history remain in the web app. MCP graph-read tools and in-app AI graph-read tools use the same pure query functions over the canonical branch graph.

Install and configure a client

Install the published nodeable-app npm package with Node.js 20 or newer. Its executable is nodeable-mcp. The MCP server README has client setup examples and package-local development instructions.

Create a personal API token on signed-in dashboard Settings → API Tokens (account settings and API tokens); provide it to the MCP process as NEXUS_API_TOKEN. Treat it as a secret: use your MCP client's environment/secret facility and do not commit it to configuration files.

Use the production API base URL https://api.nodeable.design/api. For a local API running in the repository's Docker Compose stack, use http://localhost:3003/api. The MCP process must be able to reach the selected API URL.

A minimal client configuration follows; replace the token placeholder using the client's secure environment-variable mechanism rather than storing a real token here:

{
  "command": "npx",
  "args": ["--yes", "--package=nodeable-app", "nodeable-mcp"],
  "env": {
    "NEXUS_API_BASE_URL": "https://api.nodeable.design/api",
    "NEXUS_API_TOKEN": "<set securely>"
  }
}

The client configuration above sets the API URL and token through environment variables; the package also supports optional workspace and branch defaults, agent skill resources, and the tools listed in the safety guidance below.

Write access and safety

MCP write tools are disabled by default. An operator must explicitly enable them for an authorized process with NEXUS_MCP_ENABLE_WRITE_TOOLS=true (or launch with --allow-writes / NEXUS_MCP_ALLOW_WRITES=true). An explicit NEXUS_MCP_ENABLE_WRITE_TOOLS=false remains a hard deny. Every write operation must also include requireConfirmation: true; enabling writes does not itself confirm a particular change.

Your API token's permissions and role still apply. Start with read-only discovery and review proposed changes before applying them. For source synchronization, export the complete branch first: omitted objects can be removed by synchronization. Run preview_nodeable_import, inspect its diagnostics and proposed changes, and apply only when there are no error-severity diagnostics. The apply request must use the preview's baseRevision, sourceHash, and graphRevision, plus a fresh operationId and requireConfirmation: true. The graph revision binds the apply to the state you reviewed; if the graph changes, preview again rather than applying stale work.

Preview does not enable writes. For workspace AI configuration, see Workspace Settings.

Never share API tokens in AI prompts, issue text, or source files. For authentication errors, check that the process receives the intended valid token and that it remains authorized; do not blindly retry bad credentials.