Nodeable logoNodeable
~6 minute read

Connect AI Agents with MCP

Configure MCP access for external AI agents, start in read-only mode, and use preview/apply workflows for safe writes.

Connect AI Agents with MCP

Nodeable includes an MCP server that lets external AI agents read workspace context and perform controlled operations using your existing permissions.

What this is for

Use MCP when you want an AI agent to:

  • explore workspace, project, and branch context
  • read architecture graph and wiki documentation
  • generate exports (SQL, OpenAPI, TypeScript, Mermaid)
  • run preview/apply import workflows with safety checks

Before you start

You need:

  1. Access to a Nodeable workspace and branch
  2. A valid session token for API access
  3. MCP server running locally or in a trusted environment

Recommended safe setup

Start with read-only mode:

  • keep NEXUS_MCP_ENABLE_WRITE_TOOLS=false
  • verify discovery and read tools first
  • enable write tools only when your workflow requires it

Optional strict mode:

  • set NEXUS_MCP_REQUIRE_PREVIEW_SIGNATURE=true
  • this enforces preview-before-apply on import writes

Environment variables

NEXUS_API_BASE_URL=http://localhost:3001/api
NEXUS_SESSION_TOKEN=<your-session-token>
NEXUS_DEFAULT_WORKSPACE_ID=<optional>
NEXUS_DEFAULT_BRANCH_ID=<optional>
NEXUS_MCP_ENABLE_WRITE_TOOLS=false
NEXUS_MCP_REQUIRE_PREVIEW_SIGNATURE=false
NEXUS_MCP_MAX_PAGE_SIZE=200

Typical workflow

1) Discover context

  • list_workspaces
  • list_workspace_projects
  • list_project_branches

2) Read branch design context

  • get_architecture_graph
  • query_nodes
  • list_wiki_pages

3) Generate artifacts

  • export_typescript
  • export_openapi
  • export_sql

4) Apply model changes safely (optional)

  • run a preview tool first (for example preview_sql_import)
  • review impact
  • apply with explicit confirmation
  • create branch snapshot before large applies or merges

Safety expectations

  • Your API role still controls what the agent can do
  • Write tools can be disabled globally
  • High-impact tools require explicit confirmation metadata
  • Preview/apply is the default pattern for import-based changes

Common issues

401 or 403 errors

  • token is missing, expired, or invalid
  • your role does not allow the requested action

Write tools unavailable

  • NEXUS_MCP_ENABLE_WRITE_TOOLS is still false

Apply rejected after preview

  • preview signature may be missing or mismatched
  • run preview again and use the latest previewSignature