> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acornops.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP and tools

> Configure built-in target tools, remote MCP servers, public headers, and write controls

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](/developer/integrations). Use this page when you are configuring tools that AcornOps can call.

## Tool sources

| Source                          | Owner                     | How tools appear                                                                                                                                                                                                     |
| ------------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AcornOps workspace-native tools | Control plane             | The Agent's **Capabilities → Tools** page lists code-owned tools separately. An owner or admin grants them to any specialist Agent.                                                                                  |
| Builtin Kubernetes tools        | AgentK                    | The connected agent advertises tools and AcornOps shows them in the target tool catalog.                                                                                                                             |
| Builtin VM tools                | AgentV                    | The agent advertises strict, read-only Linux/systemd tools over `tools/list`; the control plane synchronizes complete input, output, artifact, timeout, and capability contracts into the gateway for the VM target. |
| Remote MCP servers              | Workspace Agent or target | Owners or admins choose **Add MCP server**, then connect the endpoint by URL or browse configured registries from the Agent's **Capabilities** page or target **MCP servers** page.                                  |

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/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.

| Field                | Purpose                                                                |
| -------------------- | ---------------------------------------------------------------------- |
| `name`               | Operator-visible server name.                                          |
| `url`                | HTTPS MCP server endpoint in production.                               |
| `enabled`            | Turns server use on or off without deleting configuration.             |
| `publicHeaders`      | Optional non-secret headers sent to the remote MCP server.             |
| Authentication       | Bearer token or a validated custom header for authenticated endpoints. |
| Credential ownership | No credential, workspace-managed, or individual.                       |

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:

| Deployment target | Settings                                                                                                                                    |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Kubernetes        | `components.llmGateway.mcpEgress.allowedHosts`, `allowPrivateNetworks`, `allowLocalAddresses`, and `networkPolicies.extraEgress.llmGateway` |
| VM Compose        | `MCP_EGRESS_ALLOWED_HOSTS`, `MCP_EGRESS_ALLOW_PRIVATE_NETWORKS`, `MCP_EGRESS_ALLOW_LOCAL_ADDRESSES`, and `REMOTE_MCP_ENABLED`               |

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](/use/connect-kubernetes#write-confirmation-policy) for Kubernetes write confirmation behavior, [Connect a Linux VM](/use/connect-vm#tools-and-mcp) for VM tool behavior, and the API reference sidebar for public endpoint schemas.