DocsIntegrations

Plugins & MCP

Connect a tool once and every compatible agent gets its MCP tools — locally, over SSH, in the cloud, and inside containers. Credentials stay in the Keychain and never touch a worktree.

A plugin is one connectable bundle: MCP servers, skills, native context providers (the @-mentionable issues and pages), and a short instructions note appended to the agent's prompt.

Connect it once in Settings → Plugins. Every compatible agent you launch after that — in any worktree, on any machine — gets the tools, with credentials resolved at launch and never written into your repository.

Why this is different#

Most editors let you paste an MCP config into one agent's dotfile. Agentastic treats the integration as the unit and the agents as consumers:

One connection, every agent. Claude Code, Codex, OpenCode, Amp, and GitHub Copilot each want MCP configured in a different place and format. Agentastic writes each one's native format at launch, so you never hand-maintain five config files.
Credentials never land in the repo. Tokens live in the macOS Keychain and are interpolated into a private, launch-scoped config file. The worktree, the typed shell command, and your shell history contain only a path.
It follows the agent. The same plugin is staged onto remote SSH hosts, cloud VMs, and inside containers — as 0600 files inside a 0700 session directory under the remote user's home.
Additive, never destructive. Your own ~/.claude.json, repo .mcp.json, and config.toml keep working. Agentastic adds to them for one launch; nothing of yours is rewritten.
De-duplicated. If you already configured the same server yourself, Agentastic recognizes it — even under a different name — and doesn't register it twice.

Built-in plugins#

Fourteen plugins ship with the app, listed as By Agentastic and pinned to exact server versions in each release (never @latest, so a supply-chain bump can't ride in silently).

Plugin	What agents get
Linear	MCP tools + `@`-mention issues
Sentry	MCP tools + `@`-mention issues, with the latest event and stack trace
Notion	MCP tools + `@`-mention pages
Slack	MCP tools + a CLI the agent can call on its own machine — see Slack
GitHub	MCP tools + `@`-mention issues
GitLab	MCP tools + `@`-mention issues (self-hosted hosts supported)
Monday	MCP tools + `@`-mention items
Trello	MCP tools + `@`-mention cards
Plane	MCP tools + `@`-mention issues (self-hosted hosts supported)
Jira	`@`-mention issues
Asana	`@`-mention tasks
Plain	`@`-mention threads
Featurebase	`@`-mention posts
Forgejo	`@`-mention issues (self-hosted hosts supported)

The last five have no MCP server yet, but their attachments, instructions, and skills reach every agent — those channels are agent-agnostic. See Issue Tracking for the mention workflow.

Connecting a plugin#

Open Settings → Plugins.
Select the plugin in the left column.
Fill in its credential fields and any non-secret settings — a Jira site URL, a GitLab host, a Plane workspace slug.
Connect.

Secrets go to the macOS Keychain under plugin.<plugin>.<KEY>; non-secret settings are stored in Agentastic's preferences. Some fields are optional and unlock extra features without blocking the connection — Slack's app-level token, for example, is only needed for incoming requests.

The detail pane shows exactly what each server runs — the full command line or endpoint URL — plus which of your installed agents will receive it.

Connecting Linear or Sentry reuses the token the older native integration already stored, so there is nothing to re-enter.

Which agents receive MCP tools#

MCP arrives through each provider's own launch-scoped mechanism:

Agent	How Agentastic delivers it
Claude Code	`--mcp-config <file>` — additive to `~/.claude.json` and repo `.mcp.json`
Codex	A per-session `CODEX_HOME` whose copied `config.toml` gains merged `[mcp_servers.*]` tables
OpenCode	A private `OPENCODE_CONFIG` file, loaded additively
Amp	Additional JSON MCP configuration via its native per-session flag
GitHub Copilot	Additional JSON MCP configuration via its native per-session flag
Every other agent	No MCP channel yet — skills, instructions, and `@` attachments still apply

Custom connections that wrap one of these CLIs get delivery too: Agentastic infers the agent from the launch command when there's no catalog id.

Choosing plugins per run#

The Agent Home prompt card pins every plugin going out with this run as a chip. Remove a chip to skip that plugin for this launch only; use the + menu to add a connected plugin that is globally off.

Overrides store only the deviation from a plugin's global setting, so an untouched run keeps following Settings. When you schedule a task, the selection is frozen into a complete map — the scheduled run delivers the same plugins months later even if you have since changed the defaults.

Your own plugins#

Three scopes exist, and on an id collision the highest-precedence one wins: workspace → personal → built-in. A repository can therefore pin its own variant of a built-in plugin.

Add a personal MCP server#

Settings → Plugins → Add MCP Server takes a name, a command or URL, arguments, and environment or header values. Any value you mark as a credential is written to the Keychain before the manifest is saved, and the manifest references it as ${secret:KEY}.

Use the same sheet to edit one server of an existing plugin without disturbing the rest.

Install a plugin folder#

Point the installer at a folder containing a plugin.json and it is copied into ~/Library/Application Support/Agentastic.dev/Plugins/<id>/. A manifest declares:

json

{
  "id": "acme",
  "name": "Acme",
  "description": "Acme's internal tools.",
  "auth": { "kind": "token", "secrets": [{ "key": "ACME_TOKEN", "label": "API token" }] },
  "configFields": [{ "key": "ACME_HOST", "label": "Host", "defaultValue": "https://acme.internal" }],
  "mcp": {
    "servers": {
      "acme": {
        "transport": "stdio",
        "command": "npx",
        "args": ["-y", "@acme/mcp-server@1.4.0"],
        "env": { "ACME_TOKEN": "${secret:ACME_TOKEN}", "ACME_HOST": "${config:ACME_HOST}" }
      }
    }
  },
  "skills": ["skills/acme-runbook"],
  "instructions": "Use the `mcp__acme__*` tools for Acme services.",
  "dedupeAliases": ["acme", "@acme/mcp-server"]
}

transport is stdio (launches a process) or http (points at url, with headers). skills are folders inside the plugin that install as Skills. dedupeAliases list the other names the same server might already be configured under.

Workspace plugins#

A repository can ship plugins at .agentastic/plugins/. Because that means running repo-controlled commands, a workspace plugin is inert until you approve its exact manifest hash. Change the manifest and it needs approval again — a pull request cannot quietly swap a server's command out from under you.

How secrets are handled#

${secret:KEY} and ${config:KEY} are resolved at delivery time only. Nothing is expanded when you save a manifest, and no resolved value is ever stored on disk outside the launch-scoped file.

If a reference can't be resolved — a missing token, a config field you never filled — the reference is left verbatim so the misconfiguration is visible, and delivery drops that server rather than shipping a broken value to the agent.

De-duplication#

If you already run the same MCP server from your own config, Agentastic won't register it twice. Servers are matched by normalized identity rather than name:

stdio servers by package identity, with runner wrappers (npx, bunx, uvx, pnpx, uv tool run) and version pins stripped.
http servers by host and path.
Plus the manifest's dedupeAliases, for the same server published under a different name.

Remote, cloud, and containers#

Plugins follow the agent wherever it runs. On a remote host or cloud VM, resolved credentials are staged into 0600 files inside a 0700 session directory under the remote user's home; the worktree, the launch command, and shell history reference only the resulting config path. Stale artifacts are swept automatically. Containers get the same treatment inside the container filesystem.

That means an agent on a cloud sandbox can read your Linear issue and post to Slack with the same tools it has locally, without you copying a token onto the box.

Issue Tracking — connecting trackers and @-mentioning issues
Slack — the deepest plugin, including incoming tasks
Skills — the other install-once capability channel
Settings Reference — where plugins live in Settings