Actions are deliberate user-invoked commands exposed through agent-connector's runtime. They are useful when a human wants a button/menu/command affordance, but the operation is not a model-selected MCP tool and not a lifecycle hook.

Actions vs tools vs hooks#

MCP tools are for the model. Hooks are for host lifecycle events. Actions are for a human deliberately invoking a connector command from a CLI, palette, button, menu, or generated host command where the target host has an affordance.

Always keep a CLI fallback#

The universal form is agent-connector action <host> <id>. Host-native buttons and commands can call the same entrypoint, but a documented CLI path makes support and automation possible on every host.

# Same action through the universal fallback entrypoint
agent-connector action warp refresh-index --connector acme-db
agent-connector action hermes open-dashboard --connector acme-db

# Prefer this fallback in docs and support runbooks.
# Host-native buttons/commands can call the same entrypoint where wired.

The dispatch flow#

User invokes a host action
        |
        v
Host affordance calls the agent-connector action entrypoint
        |
        v
Runtime resolves connector + action id
        |
        v
action.run(ctx) executes deliberate user command
        |
        v
Result is returned to the host affordance

The important beginner distinction is authority: an action is a human command, so its UX should make the operation obvious before it runs. If the model should decide when to call something, it belongs in MCP tools.

Define an action in a connector#

An action has a kebab-case id and a run(ctx) handler. Add label, icon, placement, and confirm when the host affordance can display them. Use hosts only when one host needs different user-facing metadata or execution path; the top-level handler remains the fallback.

import { defineAction, defineConnector } from "@ken-jo/agent-connector/sdk";

const refreshIndex = defineAction({
  id: "refresh-index",
  label: "Refresh schema index",
  description: "Refresh the local schema index.",
  icon: "refresh-cw",
  placement: "command-palette",
  confirm: {
    title: "Refresh schema index",
    message: "Rebuild the local acme-db schema index now?",
  },
  async run(ctx) {
    await refreshLocalSchemaIndex(ctx.projectDir);
    return { message: `Refreshed acme-db index for ${ctx.host}` };
  },
  hosts: {
    warp: {
      label: "Refresh acme-db",
      description: "Refresh the schema index for this Warp workspace.",
      placement: "workflow",
      confirm: false,
      async run(ctx) {
        await refreshLocalSchemaIndex(ctx.projectDir);
        return { message: "Warp workspace index refreshed." };
      },
    },
  },
});

export default defineConnector({
  server: { transport: "stdio", command: "node", args: ["./my-mcp-server.mjs"] },
  actions: [refreshIndex],
});

How host affordances map#

Host documentation usually describes commands, plugins, menus, workflows, or MCP registration separately. agent-connector treats actions as a connector-level runtime surface and lets adapters bind that runtime to a native affordance only where the host has a verified place to do so.

Cross-validation for action hosts#

An action host is listed only when its adapter sets supportsActions and implements a concrete host affordance emitter, not merely because the universal agent-connector action CLI exists. The fallback CLI works everywhere, but the supported-host list is only for hosts with generated native affordances.

Where host affordances are wired today#

Public coverage metadata currently marks action affordance support in 9 / 42 production-relevant adapters:

Warp, Droid (Factory), Zed, Pi, Kiro, Hermes Agent, Oh My Pi (OMP), NVIDIA NemoClaw, OpenClaw

Customization checklist#

• Name the id as a command, not a noun: refresh-index, open-dashboard, repair-install.
• Keep the operation user-triggered. If the model should choose when to run it, expose it as an MCP tool instead.
• Use per-host hosts.<id>.run overrides for UI text, platform-specific paths, or affordance-specific behavior.
• Return a short message. Actions surface errors to the user; they do not fail silently like statusline rendering.

Design rules for beginners#

• Name actions like UI commands: refresh-index, open-dashboard, repair-install.
• Keep action output concise and user-facing. It is not a tool result optimized for model reasoning.
• Do not hide dangerous writes behind vague labels. Use confirmations or dry-run previews where the host affordance supports them.
• Provide a CLI fallback path for important operations because not every host exposes action affordances yet.