MCP integration

Connect Codex to one Nodectra project through a scoped, audited and human-approved MCP workflow.

Nodectra exposes a stateless MCP Streamable HTTP JSON-RPC endpoint at:

POST https://your-studio-domain.example/api/mcp

MCP lets a trusted Codex installation inspect one assigned project and prepare engineering change proposals. It does not provide direct project mutation or Runtime control.

Security boundary

Each bearer token:

begins with ndmcp_;
is displayed once and stored by Nodectra only as a SHA-256 hash;
belongs to one project;
expires after a selected period from 1 to 365 days;
is individually revocable;
inherits the creator's current membership, Engineering Seat and subscription checks;
records every method and tool call in the MCP audit.

Runtime credentials, provider secrets, other projects and host access are excluded from the project snapshot.

Available tools

`nodectra_project_snapshot`

Returns the bounded engineering snapshot for the single project assigned to the token. It is read-only and idempotent.

`nodectra_list_change_proposals`

Lists recent human-reviewable proposals and their audit state for the assigned project. It is read-only and idempotent.

`nodectra_create_change_proposal`

Stores a strict proposal containing one or more supported operations:

CREATE_OBJECT
CREATE_MODBUS_DEVICE_BATCH
CREATE_TEMPERATURE_WORKFLOW
UPDATE_OBJECT_CONFIG
CREATE_BINDING

The result is a PENDING proposal with a content hash. No project change is applied at tool-call time.

What MCP cannot do

MCP has no tool to:

apply or approve a proposal;
deploy or roll back a project;
start, stop or command Site Runtime;
write a physical Point;
access another project;
read server secrets or host files.

Create a token

Open Dashboard → Agents.
Find Project-scoped MCP.
Select the project.
Enter a connection name and validity period.
Select Create token.
Copy the revealed token immediately. It is not shown again.

Only organization Owners and Admins can manage MCP access tokens.

Configure Codex

Keep the plaintext token in a local environment variable:

export NODECTRA_MCP_EXAMPLE_PROJECT_TOKEN="ndmcp_replace_with_revealed_token"

Add the generated server block to a trusted Codex configuration:

[mcp_servers.nodectra_example_project]
url = "https://your-studio-domain.example/api/mcp"
bearer_token_env_var = "NODECTRA_MCP_EXAMPLE_PROJECT_TOKEN"
required = true
default_tools_approval_mode = "writes"

The token is sent through the standard Authorization: Bearer header. Production endpoints must use HTTPS without embedded credentials, query parameters or fragments. Localhost HTTP is accepted only for local development.

Review a proposal

Codex reads project snapshot
          ↓
Codex creates strict proposal
          ↓
Nodectra validates and stores PENDING proposal
          ↓
Authorized engineer reviews operations and diff
          ↓
Studio revalidates current project revision and scope
          ↓
Engineer approves or rejects

Approval runs through the same serializable, audited project transaction used by built-in agents. A proposal expires after its configured review window and cannot silently apply itself.

Revoke access

Return to Dashboard → Agents, locate the token and choose Revoke. Revocation takes effect on the next request. Review the MCP audit list for unexpected reads or proposal attempts.

Treat an MCP token like a project-scoped engineering credential. Never commit it to source control, Markdown, TOML or shell history.

On this page