Skip to main content

Upgrade a GitHub-managed agent to the platform

Move an existing GitHub-managed agent to platform-managed configuration, so its config lives in MintMCP instead of agent.yml and it gets its own identity and connector bundle.

New agents are platform-managed by default. Agents created earlier, whose configuration still lives in an agent.yml file, keep working unchanged, and you can move one over whenever you're ready. The upgrade is one click from the agent's Settings tab, and it cannot be undone.

Before you upgrade​

  • Permissions. You need both org:agents:manage and org:vmcps:manage, because the upgrade also creates or adopts the agent's identity and connector bundle (a vMCP).
  • One agent-identity bundle. The upgrade only adopts an existing agent-identity bundle. If the agent is connected to exactly one such bundle, it becomes the agent's identity and its connectors, tool permissions, and credentials carry over unchanged. More than one agent-identity bundle blocks the upgrade until you disconnect the extras. An ordinary shared vMCP you connected by hand is not adopted: it stays connected as-is and the upgrade provisions a fresh identity alongside it.

Upgrade the agent​

  1. Open the agent, go to the Settings tab, and find the Upgrade to platform card.

  2. Read the preview. It tells you what will happen to the agent's identity:

    Preview saysWhat it means
    "A new agent identity and connector bundle will be created for it."The agent had no agent-identity bundle, so the upgrade provisions a fresh one. Any ordinary shared vMCP stays connected separately.
    "Its existing identity bundle … becomes the agent's identity — connectors, tool permissions, and credentials carry over unchanged."The agent's one agent-identity bundle is adopted as its own identity.
    A blocked reasonThe upgrade can't proceed until you resolve it. See If the upgrade is blocked.

  3. Click Upgrade to platform and confirm. The upgrade cannot be undone.

When you confirm, the platform copy becomes the source of truth immediately. That switch happens the moment you click, not when a pull request merges. From that point the agent reads its config from MintMCP, and any agent.yml still in the repo is ignored.

The upgrade then cleans up the repository, as a best-effort follow-up:

  • Deletes agent.yml from the repository, so the stale copy is gone.
  • Updates the agent's AGENTS.md (or CLAUDE.md) with a platform section describing how its config now lives in MintMCP.
  • Regenerates the agent's workflow file, which stays in the repo as a trigger bridge for scheduled runs.

On a repository with branch protection, these cleanup changes arrive as a single pull request titled "Migrate <slug> to the MintMCP platform". Merging it is housekeeping: it removes the ignored agent.yml and lands the instruction and workflow updates. It is not the thing that completes the upgrade, which already happened when you confirmed. Slack triggers, secrets, and model credentials keep working without changes.

If any part of the cleanup can't be written (for example branch protection blocks a direct push, or the instruction file couldn't be updated), the agent shows a Needs attention status with a note about what remains. The agent is already platform-managed and running; finish the outstanding cleanup by merging the pull request it opened, or contact us if the status doesn't clear.

If the upgrade is blocked​

The preview names the reason and, in most cases, how to clear it. Resolve it, then reopen the Upgrade to platform card.

Blocked reasonHow to unblock
The agent is connected to more than one agent-identity bundle.On the Connectors tab, disconnect all but one agent-identity bundle, then upgrade.
The agent's identity bundle already belongs to another agent.On the Connectors tab, disconnect the claimed bundle and either connect an unclaimed agent-identity bundle or upgrade with none connected (a fresh identity is created). Archiving the other agent does not release the bundle; to transfer ownership, contact us.
agent_dir in agent.yml does not name the directory the file lives in.Fix agent_dir so it matches the agent's own directory, then upgrade.
agent.yml exceeds platform config bounds (for example an oversized prompt).Shrink the offending field, then upgrade.
agent.yml is missing, fails to parse, or fails validation.Fix the file so it parses and validates, then upgrade.
The agent is already platform-managed.Nothing to do.

If a blocker persists after you've cleared it, or the preview reports the platform row is malformed, contact us and we'll help unblock it.

After the upgrade​

The agent card now shows a Platform V2 badge, and configuration moves off the repository:

  • Humans edit the agent's model, secrets, Slack connection, and permissions on the Settings tab, and its tools on the Connectors tab, the same way as before the upgrade.
  • The agent itself reads and replaces its own configuration through two tools in its MCP tool list, get_agent_config and update_agent_config, with version checking. Its slug and agent_dir are immutable.
  • Schedules are no longer edited in the UI or in agent.yml. Ask the agent to change its schedule, and it updates triggers.schedule in its own configuration (cron in GitHub Actions syntax, UTC). A changed schedule only starts firing once the regenerated workflow lands: on a branch-protected repo, merge the pull request the change opens, or have an admin run Sync workflow on the agent. An invalid cron expression is rejected.

Next steps​