This guide is for administrators who enable, secure, and operate Proxus MCP Server. It covers the production boundary around AI-agent access; the agent integration guide covers how a user connects and runs workflows.
Administration Outcome
A production-ready MCP deployment should provide all of the following:
- One approved HTTPS endpoint for MCP traffic
- Authentication bound to the current MCP transport session
- Proxus role, object, and field permissions enforced on every protected call
- Administrator-only guarded telemetry analysis
- No direct database credentials or control-system sessions exposed to agents
- Bounded queries, rate limits, session limits, and audited operations
- Structured, secrets-free errors that tell an agent how to recover safely
Production Rollout Checklist
- Prepare HTTPS Publish the Proxus Hub behind a trusted HTTPS endpoint. Confirm certificate validity, proxy forwarding, and the final public origin before enabling remote clients.
- Pin the server origin Set the canonical MCP server origin in the MCP section of the Configuration Reference. Do not rely on a request-supplied host outside loopback development.
- Choose discovery exposure Decide whether anonymous clients can see tools plus a secrets-free overview, tools only, or no discovery beyond the protocol handshake and authentication helpers.
- Prepare roles Create or review Proxus users and roles. Grant only the entity, object, field, log, and UNS scopes required for each workflow.
- Prepare telemetry access Configure a dedicated read-only telemetry account and bounded resource limits. Keep unrestricted or shared production credentials disabled.
- Choose the write posture Start read-only. Enable only the specific mutation methods required by an approved business workflow; keep delete and bulk operations independently blocked unless explicitly needed.
- Set operational limits Configure per-user request limits, graph/telemetry-specific limits, concurrent sessions, session lifetime, and optional IP restrictions.
- Enable audit operations Confirm authentication, authorization failures, tool calls, guarded queries, and approved mutations are visible through the intended audit and support workflow.
- Run the acceptance matrix Validate anonymous, restricted-user, administrative, invalid-argument, logout, and stale-client behavior before exposing the endpoint to production agents.
Connection and Origin Boundary
MCP clients connect to one Streamable HTTP endpoint:
https://your-proxus.example/mcpProduction deployments must use an administrator-configured canonical origin. Additional Proxus endpoints or browser origins are explicit exceptions, not automatic trust derived from the incoming Host header.
The origin policy rejects:
- A different host supplied by an agent or tool argument
- Browser requests from an unapproved Origin
- Origin values containing credentials, paths, queries, or fragments
- Silent fallback from a production endpoint to a development destination
Use TLS Certificates and the MCP section of the Configuration Reference together when preparing the endpoint.
Anonymous Discovery Policy
Choose the smallest discovery mode that still supports your clients:
| Mode | Anonymous behavior | Recommended use |
|---|---|---|
| Tools and overview | Tool contracts and a secrets-free bootstrap overview are visible; data calls still require login | Default for general MCP compatibility |
| Tools only | Tool contracts are visible; overview, resource, and prompt discovery are reduced | Restricted environments where clients can route from tool schemas |
| Disabled | Unknown or disabled discovery modes fail closed; only protocol and authentication bootstrap remains | Highly controlled deployments with preconfigured clients |
Tool visibility never grants data access. Every protected call is authorized again at execution time.
Identity and Permission Model
MCP does not create a parallel permission system. The authenticated Proxus user and existing role permissions remain the authority.
| Surface | Required authorization |
|---|---|
| Protocol handshake, tool discovery, authentication helpers | Anonymous bootstrap policy |
| Entity schema and records | Authenticated user plus visible entity and field scope |
| Current device health | Authenticated user plus visible Device scope |
| Operational Graph | Authenticated user; graph snapshot is isolated to that security scope |
| Operational logs | Explicit log permission plus visible gateway scope |
| Raw metadata and guarded telemetry SQL | Administrative Proxus role |
| Mutations | Authenticated user, allowed server method, entity/object/field permission, and explicit human intent |
Administrative users can legitimately see the whole configured estate. They cannot prove that negative role isolation works. Acceptance testing therefore needs a restricted account with one known in-scope object and one known out-of-scope object.
UNS and device scope
Where a workflow uses UNS-scoped data, explicit deny takes precedence over allow and path matching follows segment boundaries. Do not grant a broad parent path merely to make one agent test pass. Use UNS Topic Permissions to define and review the scope.
Session and Downstream Identity
The normal stateful flow is:
MCP transport session
-> authenticated Proxus business session
-> current Proxus user and role scope
-> protected tool and downstream requestInbound HTTP authorization or general cookie headers do not replace the authenticated MCP business session when a protected tool calls another Proxus endpoint. Tool arguments cannot provide a different password or redirect the session to another host.
A protocol-bound login intentionally does not require a compatibility cookie or a business session identifier in subsequent tool arguments. Compatibility state is used only for clients that cannot preserve the protocol session. Logout invalidates the bound business session; the next protected call must be rejected until the user authenticates again.
Telemetry Security and Resource Limits
Guarded telemetry analysis is administrator-only and read-only. Configure a dedicated account with read access only to the required telemetry and log tables. Do not silently fall back to a broad production database account.
Set finite limits for:
- Rows and bytes read
- Result rows and result bytes
- Query execution time
- Memory use and worker threads
- Per-user telemetry request rate
The server also validates the query structure. Writes, unrelated databases or tables, external sources, table functions, multiple statements, and attempts to escape the approved telemetry surface are rejected.
Resource-limit errors are expected safety outcomes. An agent should aggregate earlier, narrow device and key scopes, or split independent scopes; it must not ask the administrator to weaken production limits for one analysis.
Read-Only and Controlled-Write Profiles
Recommended initial profile
- Read operations only
- Administrative telemetry enabled only for named administrators
- Delete and bulk operations blocked
- Explicit IP restrictions where the deployment network permits them
- Conservative request and session limits
- Audit logging enabled
Controlled-write profile
Enable controlled writes only when a defined business workflow requires them. Keep these conditions together:
- The human explicitly requests the exact change
- The agent reads the current target first
- The method is enabled by server policy
- The Proxus user can write that object and every changed field
- The request carries a truthful change intent and minimal body
- The agent reads the target again and reports the verified result
Do not expose direct OT setpoint or control-system sessions through MCP. Approved business-data changes are not a reason to open a control path.
Audit and Monitoring
Review MCP operations alongside normal platform audit and system diagnostics.
Monitor at least:
- Successful and failed authentication
- Session conflicts and expired sessions
- Authorization denials by user and tool family
- Origin and endpoint rejections
- Rate-limit and query-resource-limit events
- Guarded telemetry query outcomes
- Mutations, change intent, target, and verification result
- Repeated invalid arguments or suspicious destination attempts
Audit output must not include passwords, session identifiers, tokens, cookies, database credentials, function code, connection parameters, notification secrets, or raw dashboard SQL.
See Audit Logs and System Logs for the platform-wide operational model.
Acceptance Matrix
Run this matrix from a fresh MCP transport after every server upgrade or security-policy change.
| Test | Expected result |
|---|---|
| Anonymous protected tool call | JSON-RPC authentication-required error; no operational data |
| Tool discovery | Current catalog; retired tools absent |
| Restricted user, in-scope object | Authorized data only |
| Restricted user, known out-of-scope object | No data leak; indistinguishable missing/not-visible boundary where applicable |
| Administrative telemetry query | Guarded read succeeds within configured limits |
| Query against an unrelated system table | Rejected before execution |
Missing graph oid or invalid direction | Recoverable tool_arguments_invalid result |
| Fake inbound authorization or cookie header | Cannot replace the protocol-bound Proxus identity |
| Logout followed by protected call | Authentication required |
| Agent-supplied destination | Rejected by endpoint policy |
| Configuration unchanged during observation window | No new periodic edge polling or reconciliation traffic |
Record the server version, test account type, time, and high-level result. Never paste credentials, session identifiers, or raw tokens into the report.
Upgrade and Tool Catalog Behavior
An MCP business login and the client’s tool catalog have separate lifecycles.
- Login or logout changes the Proxus business session.
- It does not force a client to discard a cached tool list.
- Proxus sends the standard tool-list change notification after initialization.
- A client that still shows a retired tool must fully reconnect the MCP transport and refresh discovery.
Test upgrades from a new transport. Do not use a successful login as proof that the client loaded the current tool catalog.
Troubleshooting
The agent sees tools but calls are denied
This is expected when discovery is visible but the current transport has not authenticated. Call auth_whoami, then let the human provide the intended Proxus account.
An administrative test cannot prove access denial
Use a restricted test account and known in-scope/out-of-scope objects. A missing random identifier tests only not-found behavior.
A telemetry query reaches a resource limit
Keep the requested time window when possible, remove unused columns, aggregate earlier, and split independent device or key scopes. Do not repeat the unchanged query.
The client still exposes an old tool
Close the MCP transport, create a new connection, and refresh tools/list. Repeating auth_login is not a catalog refresh.
Browser-origin requests are rejected
Verify the browser’s exact scheme, host, and port against the administrator-approved origin. Do not add wildcard origins to bypass the check.