Skip to content

AI Agents ​

An AI agent lets an MCP client work with Ordyn through individually allowed tools. It connects through OAuth and uses the agent's access, independently of the administrator who connected it.

Agents can read diagnostics, inspect configuration and submit proposals. With Review proposals and Allow agent to apply, they can explicitly approve and apply proposals. Submitting a proposal leaves it pending until approval. Separately granted management tools let agents run jobs and operate endpoints directly. Configuration and management have separate access controls. Protected configuration values use protected references. Applied schedules and automations can also cause work to run.

Super administrators manage agents under Administration → AI Agents. Open an agent to view its overview, tools, connections and audit history.

Configure an agent ​

Create an agent with a name and description, then open its Tools tab and select Add tools. New agents have no tools enabled. Choose Configuration and diagnostics, Management or Documentation, then select the tools and their scope. Configuration tools also require the configuration types they may access. You can add several tools with the same scope together.

  • Diagnostic tools are enabled individually and work across the whole installation. They have no tenant or folder restrictions.
  • Documentation tools provide configuration references and management command help for the installed version. They are global and grant no access to live configuration, diagnostics or operations.
  • Management tools perform operations directly. Grant each tool for its supported targets: all targets, a tenant, an endpoint folder and its descendants, or one endpoint. Management does not use proposal review.
  • Configuration tools require selected configuration types and a global, tenant or folder scope. Folder scopes include descendants. Global access covers the selected types throughout Ordyn; tenant access does not include global library items.

Add the Health diagnostic tools to let an agent summarize issues, search active or resolved findings, and review issue history.

For folder access, choose the Folder type first. Endpoints and IPAM require a tenant; Groups can use tenant or global folders. Libraries such as Scripts and Jobs use global folders. The configuration type list shows the types supported by that folder tree. A Scripts folder grants access to scripts stored there; an Endpoints folder grants access to endpoints and their configuration, including job assignments, rather than the job definitions in the Jobs library.

Choose Edit from a tool row's context menu to replace the tool or change its scope and configuration types. Add a tool again with another scope to allow it in several locations. Access is specific to each tool: allowing a tool to read scripts does not allow another tool to change them. Include read access to the resources a proposal needs to reference, such as a job's scripts and Runner pool.

To prepare proposals, the client needs tools for discovering and reading the relevant configuration, assembling changes, validating them and submitting them. Scope proposal tools to all types and locations that the agent may include in a proposal. Changes to an agent's tool access take effect on subsequent requests, including requests for pending diagnostic results.

For proposals with files, also enable Create text files or the file upload tools. Binary uploads require the client to have a shell or HTTP tool that can read local files and send them to a temporary upload URL. Download external installers locally first. Read file content lets the agent inspect accessible attachments; Analyze package files can suggest metadata for uploaded EXE, MSI and MSP files or accessible package attachments, including earlier revisions. The agent can retrieve the file and package guides from Ordyn's configuration documentation.

Find proposals lets the agent locate and resume its drafts across connections. Reserve proposal resources lets it extend a draft with more related resources. Read revision history provides access to earlier applied configuration, and Find configuration options provides eligible agent releases and certificate authorities for jobs and services.

Preview configuration matches lets the agent check dynamic group membership, Windows Update rule matches and a software policy for an endpoint before submitting. It uses current inventory and related proposed changes, within the tool's allowed scope. Previewing does not change memberships, approve updates or run jobs.

Grant management access ​

Select Management when adding tools. Choose the operations the agent needs and the targets it may operate. Add scoped reading tools alongside operational tools so the agent can discover endpoints and jobs, inspect inventory, and retrieve instruction and job results without installation-wide diagnostic access.

For job tools, combine the target scope with All jobs, One job, or a Job library folder and descendants. For example, grant Run job for an endpoint folder and restrict it to a Maintenance folder in the Jobs library. Both restrictions must match the same grant; access to a job in one grant cannot be combined with a target from another grant.

A job must also have Allow AI-agent execution enabled before an agent can start it. This applies even with global management access. The flag is ordinary job configuration: an agent with the appropriate configuration tools can propose changing it and can apply that proposal when its proposal setting and review access allow it. A permitted job can perform its configured steps without granting every step as a standalone management tool. Starting a child job still requires access to that job and its targets, and the child must allow AI-agent execution.

For endpoint troubleshooting, choose Exact endpoint as the scope, select the tenant and endpoint, and grant the required tools.

Management operations execute directly with the same endpoint availability, capability, licensing and consent requirements as their corresponding Ordyn features. Remote Access tools provide session lifecycle and diagnostic information; they do not provide an interactive screen, keyboard, mouse or clipboard. User, role, AI-agent access and credential administration are outside management access. Browser viewer controls and human-authored comments remain in the application.

Removing a grant, disabling the agent, or revoking its connection prevents new work. A job target that has already started may finish its admitted workflow. Targets still waiting to start, child jobs and newly selected endpoints require current access. An operator can use the existing job cancellation controls to stop admitted work.

Manual endpoint operations match the actions available in the web interface, including inventory refreshes, service controls, snapshots, file and registry operations, and agent maintenance. The endpoint History shows who requested each operation and its progress or outcome. A request being accepted does not mean it completed successfully.

Use saved jobs for scripts, Docker Compose changes, update installation and other execution workflows. The agent can create and assign these jobs through the configuration proposal workflow, then run them with its job management access. Independent authoring requires Allow agent to apply, Review proposals, and the relevant configuration access; Require review keeps approval with a human reviewer.

Use management command help and results ​

Grant Read management documentation from Documentation so the agent can search command summaries and retrieve a guide for one tool. Each guide includes inputs, examples, prerequisites, retry guidance and related tools. Grant those operational tools separately.

Management reads return pages of up to 16 KiB by default. The agent can request up to 128 KiB with max_bytes, follow continuation cursors and reconstruct oversized records from ordered fragments. Job-run reads start with a summary; targets and tasks have separate pages. Inventory searches use the latest stored snapshot, so collect fresh inventory when needed.

Operations return compact acknowledgements with identifiers for reading results. Retrying an operation requires the same request_key and arguments. If files or media are still staging, preparation continues and the agent retries with that same key once ready. Completed retries return the recorded result only while the agent retains access. Report and support-bundle downloads require include_content; file content is returned in bounded chunks.

For an unavailable job execution, the agent reads the task's recovery information before attempting resolution. Resolution requires a current revision and confirmation that execution has stopped; a changed revision requires another read.

Get configuration documentation ​

Enable List configuration formats and Read configuration documentation to let an agent retrieve the JSON references supported by this installation. The agent can find formats by name or type, search guide topics and examples, and retrieve the entries relevant to its task. Complete schemas include their dependencies.

Use configuration/ formats for proposals and portable/ formats for imports and exports. Their fields and versions can differ. Complete job bundle examples include the manifest and all files needed to assemble the archive.

Investigate package discovery ​

Enable Find package discovery runs, Read package discovery evidence, and View discovery screenshots, together with the log tools needed for the investigation. Give the agent the product name and the date, time and timezone of the problem. It can inspect the run's recorded settings, browser evidence, captured screenshots and retained logs. Screenshots require capture to have been enabled for that run; retrieving service logs requires the discovery service to be connected and still retain them.

To let the agent propose a fix, also grant configuration reading and proposal tools for the relevant discovery targets, products, variants or discovery service. Include global read access to the target's LLM connection so the agent can select it and inspect its defaults. Grant proposal tools for LLM connections when the agent should also propose changes to those shared defaults. Credentials remain hidden.

Changes require explicit approval by an authorized reviewer. The diagnostic tools do not start or retry discovery runs.

Prepare Docker updates ​

Enable Search endpoints and Read endpoint Docker inventory, then give the agent the endpoint to investigate. Ask it to review Docker updates before preparing a job.

The agent uses saved results, so check how recent they are before acting on them. For Compose tag changes, provide the environment-file path explicitly. See Docker Compose jobs for the update workflow.

Connect an MCP client ​

First configure an agent, leave it enabled and add the tools it needs. A super administrator must authorize the connection in the browser.

The examples below use https://ordyn.example.com as the Ordyn API address. Replace it with your installation's address. If the web interface and API use different hostnames, use the API hostname. The MCP client must be able to reach that address, and the browser must be able to open Ordyn's sign-in page.

Generic setup ​

Use a client that supports remote MCP servers over Streamable HTTP, OAuth with PKCE and Dynamic Client Registration (DCR). Configure these connection settings:

SettingValue
Server nameordyn
Server URLhttps://ordyn.example.com/api/v1/mcp
TransportStreamable HTTP, called HTTP in some clients
AuthenticationOAuth with automatic discovery and client registration

The client registers directly with Ordyn, so you do not need to create a client ID, client secret or API key. Ordyn does not need outbound internet access for client registration or authorization. For clients with detailed OAuth settings, choose dynamic client registration and the authorization code flow with PKCE using S256.

  1. Add the server using the settings above, then start the client's OAuth sign-in flow.
  2. Sign in to Ordyn as a super administrator and choose the AI agent.
  3. Select Connect to let the client use the selected agent's tools and access.
  4. Return to the client and check that the server is connected.

All connections to an agent use its current tool grants. For read-only access, configure the agent with reading tools only. To prepare proposals, add the required proposal tools to the agent. Proposals require review by default. Allow agent to apply, together with Review proposals, permits the agent to explicitly approve and apply a submitted proposal. Submission itself leaves it pending.

Codex ​

With the Codex CLI installed, add Ordyn:

bash
codex mcp add ordyn --url https://ordyn.example.com/api/v1/mcp

Start the browser sign-in flow:

bash
codex mcp login ordyn

Complete the Ordyn consent steps above.

You can also configure the server by adding this section to ~/.codex/config.toml, then running the login command:

toml
[mcp_servers.ordyn]
url = "https://ordyn.example.com/api/v1/mcp"

Codex shares this configuration between its CLI and IDE extension on the same host. Run codex mcp list to check the saved configuration. Start a new Codex session and use /mcp to check the active connection. See the Codex MCP documentation for client settings.

Codex also has its own tool-approval settings. To allow proposal submission or review without a Codex confirmation, add the override for each tool you want it to call:

toml
[mcp_servers.ordyn.tools.proposal_submit]
approval_mode = "approve"

[mcp_servers.ordyn.tools.proposal_review]
approval_mode = "approve"

Use your configured server name in place of ordyn. The agent still needs the matching tools granted in Ordyn. Submit proposals leaves changes pending. Review proposals can approve and apply a submitted proposal only when the agent uses Allow agent to apply; Require review prevents the agent from approving and applying proposals. See the Codex approval configuration for the available settings.

Repeated sign-in requests ​

If Codex repeatedly reports Authentication required or cannot initialize the Ordyn MCP connection after a successful login, enable its experimental OAuth refresh coordination. This is especially relevant when several Codex instances share the same configuration.

Run codex features list and check that mcp_oauth_refresh_coordination is available. Add the following to ~/.codex/config.toml, or add the setting to your existing [features] section:

toml
[features]
mcp_oauth_refresh_coordination = true

Restart all running Codex clients. If you use the shared app-server daemon, restart it once for all clients that use it:

bash
codex app-server daemon restart

Restart any independent --no-daemon instances too. If Ordyn still requires authentication, run codex mcp login ordyn again, using your configured server name. Check the connection in a new session with /mcp.

This setting is an experimental Codex workaround. It does not require changes to Ordyn's OAuth configuration.

Claude Desktop ​

Install Node.js so that npx is available to Claude Desktop. Add Ordyn to your Claude Desktop MCP configuration:

json
{
  "mcpServers": {
    "ordyn": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://ordyn.example.com/api/v1/mcp"]
    }
  }
}

Replace the URL with your Ordyn API address and merge the entry into any existing mcpServers configuration. Restart Claude Desktop, then complete the browser sign-in and select the AI agent to authorize. The bridge discovers the required OAuth scope automatically.

Use the connection check below to confirm access. If the connection reports a sign-in failure after an Ordyn update, restart Claude Desktop and retry after five minutes to allow discovery metadata to refresh.

Claude Code ​

With Claude Code installed, add Ordyn:

bash
claude mcp add --transport http --scope user ordyn https://ordyn.example.com/api/v1/mcp

The --scope user option makes the server available across your Claude Code projects. Use --scope local from a project directory to configure it only for that project. This setting does not change the agent's access in Ordyn.

Start the browser sign-in flow and complete the Ordyn consent steps above:

bash
claude mcp login ordyn

Start a new Claude Code session and use /mcp to check the connection. You can also authenticate from that menu by selecting ordyn. See the Claude Code MCP documentation for client settings.

Verify the connection ​

For a simple check, enable List configuration formats and Read configuration documentation on the agent, then ask the client:

Use Ordyn to list the available configuration formats and read the guide for job configuration.

This checks access without changing live configuration. If tools are missing, check the agent's Tools tab and ask the client to search its available tools. After granting more tools, reload the client's MCP connection or start a new client session if its tool list is stale. Changing grants does not require another OAuth sign-in or a new agent.

Clients that support tool search can load tool definitions as needed. Configure this in the MCP client; Ordyn exposes the tools allowed for the connected agent.

If a tool is listed but its call is blocked by the client, check the client's tool-approval settings as well as the agent's access in Ordyn.

Manage connections ​

Changes to the agent's tool grants apply to all its connections on subsequent requests. The client refreshes its access automatically while its authorization remains valid. Sign in again if the client requests it.

Open an agent's Connections tab to inspect its connected clients or revoke a connection. Clear Enabled in the agent's edit form to disable it. Disabling or deleting the agent ends access for all its clients.

Review proposals ​

Choose Require review or Allow agent to apply in the agent's edit form. Require review is the default and prevents that agent from approving or applying proposals, even if it has Review proposals. An authorized human or another authorized agent must approve and apply its changes.

To let an agent work independently, select Allow agent to apply and grant Review proposals for the configuration types and scope it may review. The agent must explicitly submit, then approve and apply a proposal. Submission always leaves it pending. The review tool can also reject submitted proposals. Grant Find proposals, Read proposals and feedback, and Read file content when the reviewer needs to inspect attachments.

Agents can submit related creations, edits and deletions together. With Require review, nothing becomes active until a person or an authorized agent approves and applies the proposal. Open proposals under Operations → Proposals. Existing items also provide Pending changes in their own view. See Configuration revisions and proposals.

File proposals include the uploaded content. Review text templates directly, compare changed text and inspect file details or download attachments. Newly prepared files must pass malware scanning before the proposal can be submitted or applied. Retained earlier content is available under File versions.

If an agent leaves a proposal unfinished, select Discard draft from its proposal page or the proposals list. You can discard several selected drafts together. You need editing rights for all affected configuration; super administrators can also discard empty or incomplete drafts. Discarded drafts appear as Withdrawn and retain their proposed changes for inspection. Discarding does not change active configuration or require the agent to reconnect.

If a proposal is rejected or outdated, the agent can copy it into a replacement, retaining its proposed changes and completed file uploads. Changes to the active configuration must be reconciled before resubmission. Review the replacement before applying it.

Treat content an agent reads, such as log lines, file names and inventory data, as untrusted. Check that every proposed change matches the intended task.