Connect MCP tools and install plugins

MCP servers connect afk to external tools and data sources. Plugins add reusable skills, slash commands, named agents, MCP configuration, and optional executable setup code. Install only sources you trust: these extensions can execute programs on your machine.

Connect an MCP serverCopy Anchor Link

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    }
  }
}

/mcp
/tools
/mcp auth

Configuration layersCopy Anchor Link

Server definitions merge by name, with higher-priority definitions replacing the whole server entry rather than merging individual fields.

A collision produces a warning naming the displaced source. A CLI override is an additional layer, not a clean-room replacement of all other servers. Imported MCP definitions can also be enabled explicitly through migration.

Server optionsCopy Anchor Link

Values in env and headers can contain ${VAR} placeholders. Expansion reads environment variables, not shell expressions. Missing variables become empty strings with a warning. Use environment-backed credentials rather than embedding a token in a checked-in file.

For a remote server, the configuration shape is:

{
  "mcpServers": {
    "remote-tools": {
      "type": "streamable-http",
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer ${REMOTE_TOOLS_TOKEN}" }
    }
  }
}

This is an illustrative endpoint; use the actual endpoint supplied by your service. An OAuth server uses oauth: true instead of a manually managed bearer header when supported. Pending authorization URLs are also surfaced through Telegram when configured. On macOS, MCP OAuth credentials use the platform keychain; the non-macOS implementation uses the existing Claude credentials file backend.

Startup health checks and failuresCopy Anchor Link

Initial connect failures are normally warnings; other servers and the session can continue. alwaysLoad: true makes that initial failure fatal.

For an additional liveness check after the connect burst:

AFK_MCP_HEALTHCHECK=1 afk

This opt-in probe repeats tools/list on connected servers in parallel with a 5-second timeout per server. It catches servers that handshake successfully but then stop responding. Probe failures are warnings, not startup blockers, even though initial alwaysLoad connection failures are blocking. The probe is off by default to avoid an extra startup round trip.

Tool-list change notifications refresh available MCP tools without restarting the session. This does not imply that editing mcp.json reconnects servers live; start a new session after configuration changes.

Surfaces and interactive promptsCopy Anchor Link

MCP is wired into the REPL, afk chat, daemon agent tasks, and Telegram sessions. Each uses its resolved configuration and working directory. The manager belongs to the top-level session; forked subagents do not automatically inherit its MCP tools. Ask the coordinator to make MCP calls when a child needs them.

Servers may request input through elicitation. In the REPL, boolean and enum fields can use a selection menu; other fields accept typed input. Available interaction depends on the surface. Do not design unattended jobs around a server that requires a human response, and do not expect child sessions to answer elicitation prompts.

Install a plugin or marketplaceCopy Anchor Link

Manage installed extensionsCopy Anchor Link

afk plugin list
afk plugin update
afk marketplace list
afk marketplace update

For a specific installed plugin, use afk plugin update <name>, disable <name>, enable <name>, or remove <name>. Marketplace equivalents include update <name> and remove <name>. Use the names reported by the listing, not a guessed directory name. See the CLI reference for pinning, replacement, and noninteractive options.

Plugin installation state lives under ~/.afk/plugins/, with .index.json tracking enabled entries and cache/ holding marketplaces. Discovery understands nested marketplace layouts, but installed/enabled state still matters.

Object-valued marketplace sourcesCopy Anchor Link

A marketplace entry's source can be a relative path, GitHub shorthand, HTTPS URL, or a supported object. The git-subdir object clones a repository and selects a plugin directory within it:

{
  "name": "example-tools",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/example/plugin-collection.git",
    "path": "plugins/example-tools",
    "ref": "v1.2.0"
  }
}

The example shows the manifest shape, not a repository you should install. url and path are required; ref and sha are optional. Unsupported or malformed object types remain visible with a skip reason, and installation refuses that entry instead of silently dropping the whole catalog.

What plugins contributeCopy Anchor Link

Legacy Claude Code command files are parsed as prompts and listed by /skills. Their names come from the file path, not frontmatter. They remain user-invoked commands rather than automatically expanding the model's skill-routing catalog. Supported metadata such as description, argument hints, allowed tools, and model goes through the shared skill parser.

User skills can also live at ~/.afk/skills/<name>/SKILL.md without packaging a plugin. See custom skills and named agents for those layouts.

JavaScript entrypoint lifecycleCopy Anchor Link

When a manifest declares main, AFK imports that module during plugin activation before the session's skill manifest is assembled. If it exports a default function, AFK awaits it and passes the host API. Use the supplied API for registration rather than importing a separate runtime copy of agent-afk, which could register against the wrong singleton or fail in a cloned plugin without dependencies.

Activation is once per resolved entrypoint path per process, not once per session. A failing import or activation is reported without aborting session startup, and the same path is not retried during that process. Module-level side effects also run at import time. This is executable code, not sandboxed Markdown.

Plugin hooksCopy Anchor Link

There are two distinct mechanisms:

1. A plugin can ship hooks/hooks.json. Command hooks load only after you set enablePluginHooks: true in user-global AFK configuration. This is independent of enableShellHooks. Unsupported hook types are skipped with a warning.
2. A JavaScript entrypoint can call the host's registerHook API. The declaration is installed on subsequently constructed session hook registries; REPL startup also attaches declarations to its already-created registry. Handlers should derive session-specific state from their context. Exceptions are isolated, and plugins cannot disable handler timeouts with longRunning.

Do not assume /reload-plugins hot-reloads hook definitions or reruns JavaScript activation. Restart afk after changing hooks or main. See hooks for event behavior, trust settings, and Claude Code matcher compatibility.

Refresh and inspectCopy Anchor Link

/reload-plugins
/skills
/agents
/mcp
/tools

/reload-plugins invalidates discovery caches and refreshes skill and agent slash registrations, reporting counts, changed names, and installed versions. It is useful after Markdown edits, not a general process or MCP restart.

RelatedCopy Anchor Link