Skip to main content
AcornOps exposes tools to runs through four paths:
  • Workspace-native tools are owned and executed by the control plane for Workflows and, where declared, target chat.
  • Builtin Kubernetes tools are provided by the AgentK and synchronized through the control plane.
  • Builtin VM tools are provided by the AgentV and synchronized through the control plane.
  • Remote MCP tools are discovered by the LLM gateway from Agent- or target-owned MCP server installations.
Owners and admins manage tool availability. Operators can start runs and use tools allowed by their role, the target policy, and the run’s requested access mode. Built-in cluster and VM tools are AcornOps built-in target tools. They are not workspace-native tools and they are not remote MCP integrations. AgentK or AgentV advertises them, the control plane records them in the target catalog, and the runtime invokes them only through that exact target.

​
Built-in capabilities

AcornOps ships these code-owned semantic capabilities:
  • infrastructure.diagnostics.read routes to read-only built-in tools advertised by AgentK or AgentV for one exact target.
  • http.fetch.get reads configured public HTTPS text or JSON through the control plane.
  • documents.create creates a bounded PDF or Markdown document from approved Workflow evidence.
scm.repository.read is a supported semantic capability, but it is not built in. It needs a reviewed repository integration. Semantic capability IDs do not authorize tools by themselves. For infrastructure.diagnostics.read, the control plane creates a reviewed mapping from each eligible specialist Agent to the stable, target-independent Targets MCP catalog. A Workflow does not select a target when it is authored or launched. Instead, the model supplies target_id and target_type when it calls a target MCP tool. The compiled authority is the intersection of the Agent’s generic capability mapping, the acting user’s permissions, the pinned run scope, and call-time validation against the selected target’s live connector support. Workspace administrators set the Agent and Workflow ceilings. Starter diagnostics allow Kubernetes and virtual-machine target types. An administrator can narrow the Agent to exact target IDs. Operators can name a target in the prompt, but the resulting tool call cannot widen the administrator-defined scope. Remote MCP tools, skills, web search, target insights, workspace-native tools, and write-capable target tools are not included in infrastructure.diagnostics.read. If you are building a bot or workflow adapter that reacts to AcornOps events, start with Integrations. Use this page when you are configuring tools that AcornOps can call.

​
Tool sources

Newly discovered remote MCP tools stay disabled until an owner or admin reviews them. AcornOps suggests read only when the server provides an explicit, non-conflicting MCP readOnlyHint: true annotation; missing, malformed, false, or conflicting hints default to write. The reviewer can change the suggested capability before enabling each tool.

​
Workspace-native tools

The native catalog currently contains:
  • http.fetch.get, exposed as acornops_fetch, performs an unauthenticated HTTPS GET through the control plane. Configure one to 20 complete URL patterns on the Agent’s Capabilities → Tools page. A pattern may contain * only in its path or query, where it matches zero or more characters; scheme, hostname, and port always match exactly. Exact patterns do not authorize extra query values. Redirects, credentials, fragments, IP-literal and private-network destinations, binary media, responses over 256 KiB, and requests exceeding 15 seconds are rejected. Treat returned content as untrusted external data.
  • documents.create, which creates a bounded, provenance-linked PDF or Markdown document with authenticated download and idempotency per run and tool call.
documents.create defaults to PDF. Set its format argument to markdown to create a Markdown download instead. Native tools are code-owned, so granting or revoking one requires manage_agents, not manage_mcp. Assignment updates the mutable Agent definition, reviewed semantic mapping, and dependent Workflow readiness together. Internal coordinator runs cannot receive operational tools. http.fetch.get has Workflow-only invocation scope. documents.create is available to Workflows and target chat. Delegated specialist children cannot invoke workspace-native tools. Target adapters reject workspace tools; Kubernetes and VM native tools continue through AgentK and AgentV. Document creation has the internal_artifact authorization class. A read-only Workflow may create the artifact without write-run permission or per-call write approval, while persistence remains a write-audited event. AcornOps never logs chat bodies, document source, tool arguments, or document bytes.

​
Builtin Kubernetes tools

The current builtin tool set is:
  • list_resources
  • get_resource
  • get_resource_logs
  • restart_workload
  • scale_workload
  • patch_resource
Read-only runs cannot execute write-capable tools. Write-capable tools also require mutation RBAC in the Kubernetes cluster and an agent that advertises write support.

​
Builtin VM tools

The current builtin VM tool set is:
  • get_host_summary
  • list_filesystems
  • list_processes
  • get_process
  • list_services
  • get_service
  • query_logs
  • list_listeners
  • restart_service (write, enabled only for exact services selected during read-write VM onboarding)
Read-only VM runs cannot execute restart_service. A read-write run still requires remote policy, a reachable helper, and a matching enrollment-installed exact unit allowlist. The VM’s run permission mode determines whether the reviewed non-destructive restart pauses for approval or may run automatically.

​
Remote MCP server setup

Under Agents → Agent detail → Capabilities or a target’s MCP servers page, choose Add MCP server. Browse registries opens destination-bound discovery; Connect by URL opens the existing form for that Agent or target. Every installation belongs to exactly one destination. Unauthenticated installations can discover during an administrator connection test. Authenticated installations discover through the exact workspace or individual connection selected for that installation. For Connect by URL, enter the actual remote Streamable HTTP endpoint, for example https://mcp.internal.example/mcp. The URL must be absolute HTTPS and cannot contain a username, password, or fragment. Non-secret query parameters are supported; credentials must use the authentication fields. Registry roots, /v0.1 API URLs, server.json, GitHub repositories, npm or PyPI packages, containers, and stdio commands are not accepted. Internal endpoint hostnames still require the gateway egress allow-list and configured CA trust. MCP registries use a separate base-URL contract. Catalog imports store the source ID, artifact name, pinned version, digest, and import time. Runtime calls use the installed server record and do not look up the registry. Tools are authorized by server ID plus tool name. Two installed servers can therefore expose the same tool name without sharing grants or runtime authorization. Agent and target records never store credential plaintext or secret references. The gateway encrypts each connection value separately for the exact installation and owner. A change to the effective URL, authentication metadata, public headers, catalog trust, or credential ownership blocks invocation and invalidates affected connections before the new configuration can be used.

​
Public header policy

Use publicHeaders only for non-secret metadata such as client version, tenant hint, or feature flag headers required by a trusted MCP server. Public headers must follow these rules:
  • at most 64 headers per server,
  • header names must be valid HTTP header tokens and 128 characters or fewer,
  • values must be strings, 4096 characters or fewer, and cannot contain CR or LF,
  • credential-like names such as Authorization, Cookie, x-api-key, x-auth-token, and names containing token, secret, credential, api-key, or apikey are rejected,
  • platform scope headers such as x-workspace-id, x-target-id, x-target-type, x-run-id, and x-tool-name are reserved.
staticHeaders is no longer part of the public API. Send non-secret metadata as top-level publicHeaders; keep credentials in the secret-backed auth fields.

​
Header forwarding order

When the gateway calls a remote MCP server, it applies headers in this order:
  1. configured publicHeaders,
  2. platform scope headers,
  3. the installation-formatted auth header derived from the exact resolved workspace or individual connection.
Discovery and connection tests include x-workspace-id, x-target-id, and x-target-type. Runtime tool calls also include x-run-id. Public headers cannot override platform scope or auth headers. Remote MCP servers should treat platform scope headers as AcornOps-provided context, not user-controlled data.

​
Egress controls

Production gateways should require HTTPS for remote MCP servers and block private, local, and reserved network targets unless you intentionally allow specific hosts. Use these controls together: Use allow-lists for trusted internal MCP endpoints instead of enabling broad private-network access. Registry synchronization uses the same hostname, DNS, TLS, private-network, and CA controls. An air-gapped deployment can disable the official registry and use only an internal v0.1-compatible registry.

​
Credential connections

An authenticated MCP installation selects workspace-managed or individual ownership. Workspace credentials require manage_mcp; a user who can read the Agent or target and has a run capability can manage only their own individual credential. Select Connect credential, confirm the destination origin and header mode, enter the masked value, and grant explicit storage consent. AcornOps accepts at most 8 KiB of UTF-8 without trimming or normalization, rejects control characters, and verifies through authenticated tool discovery. For an authenticated manual installation, AcornOps creates the installation first and then opens Connect credential for the selected ownership mode. Pending-tool review appears only after the connection succeeds and discovery returns. Closing a failed connection dialog does not remove the installation or hide its real error state. Unauthenticated installations continue directly to discovery and pending-tool review. After Connect or Verify succeeds, the management console refreshes the owning Agent or target installation and its discovered tools without leaving the page. If that refresh fails, the credential remains connected and the console warns that the tool list may be stale with a separate retry action. A 429 response can include Retry-After; the console shows the remaining delay and keeps Connect and Verify disabled until that delay expires. Target and Agent installations never share or copy connections. Each successful discovery replaces only the resolved owner’s tool snapshot; an empty tool list is still a connected result. Newly discovered tools are added disabled and pending. Readiness fails when an exact approved tool is absent from the resolved workspace or individual connection snapshot. Workflows own no credentials; a workflow reuses its selected Agent installation. Workspace mode supports scheduled service principals, while individual mode requires a user and otherwise fails with MCP_INDIVIDUAL_USER_PRINCIPAL_REQUIRED. Missing or erroneous connections fail closed. A remote 401 or 403 clears the exact owner’s snapshot and marks that connection erroneous until it is verified, replaced, or disconnected. Changing credential ownership is destructive. Switching to individual mode removes the workspace credential; switching to workspace mode invalidates every individual connection. The gateway blocks invocation while cleanup is in progress and never falls back to the previous owner type. Connect and verify a new workspace credential before resuming unattended work. Use a dedicated, least-privilege service or bot identity rather than an employee credential. Administrators can see workspace connection status and can manage that installation-owned credential. They cannot list, read, export, replace, or disconnect another user’s individual credential. When target chat or a Workflow run fails MCP readiness, the console links to the exact Agent or target installation and highlights its Connect or Verify control. Opening that recovery link never submits a credential or starts verification. Successful repair clears the recovery parameters. If an older control plane does not return structured failure details, the link falls back to the relevant MCP page. A schedule whose last MCP outcome was auto_paused shows the bounded reason and an Agent MCP recovery link. Repair MCP before selecting Resume; AcornOps does not resume the schedule automatically. Create least-privilege credentials that expose only the tools needed for the current work. Replace and verify after provider-side rotation or revocation. Remote MCP credentials are separate from platform OIDC: OIDC signs users into AcornOps and does not authorize a remote MCP server. For source control or any other external system, create your own specialist Agent and connect the compatible MCP server by registry or URL. AcornOps discovers tools as untrusted and disabled; an administrator reviews their read/write classification and enables only the exact tools the Agent should use. AcornOps does not ship provider-specific source-control profiles, Agents, or workflows. Operators can set REMOTE_MCP_ENABLED=false to stop all external discovery and execution while leaving built-in tools operational. External MCP availability does not affect platform readiness.

​
Run permission modes

An Agent sets the maximum permission mode. A workflow or /permissions may only narrow it:
  • Read only runs only reviewed read-only tools.
  • Ask before changes runs reads automatically and requires approval for every write. This is the default.
  • Auto-run allowed changes may run only administrator-approved, non-destructive writes automatically. High-risk and destructive actions always require approval.
Every invocation intersects current principal RBAC, the pinned Agent snapshot, workflow/session restrictions, reviewed tool state, permission mode, and the exact resolved installation connection state. The generic Targets MCP catalog is stable and independent from workspace target inventory. A Targets MCP invocation additionally validates the call-time target_id and target_type against the current workspace target and its live connector tool support.

​
Write confirmations

When write confirmations are required, the run pauses before a write-capable tool call. An authorized user must approve or reject the specific pending write before it runs. The default timeout is 300 seconds. Rejection and timeout do not call the target connector. Approval executes the queued write once. AgentV restart requests use stable operation IDs and never automatically retry an unknown outcome. See Connect a Kubernetes cluster for Kubernetes write confirmation behavior, Connect a Linux VM for VM tool behavior, and the API reference sidebar for public endpoint schemas.