Skip to main content

Create your first Coworker Agent

Connect a GitHub repository, create an agent in it, and trigger its first run.

Prerequisites​

  • Coworker agents enabled for your organization (Enterprise plans, currently in beta)
  • Admin access in MintMCP (permission to manage agents)
  • Permission to install a GitHub App on the repository's organization
  • A model credential: an Anthropic API key, Claude subscription token (claude setup-token), or API key for a Claude-compatible provider for the Claude Agent harness; or an OpenAI API key for Codex

Connect GitHub​

  1. Open Coworker Agents in MintMCP at app.mintmcp.com/agents.
  2. Click Install GitHub App and grant the MintMCP GitHub App access to the repository (or repositories) where agents will live.
  3. Back in MintMCP, pick the repository from the Select a Repository card. You can connect more repositories later from the page header.

If the repository is empty, MintMCP shows an Initialize repository button that creates an initial commit.

Set up the repository​

Agents share workflow files and helper scripts that live in the repository. When the repository doesn't have them yet, MintMCP shows an Agent infrastructure setup needed card listing the files it will create.

  1. Click Set up repository. MintMCP commits the shared agent infrastructure to the default branch.
  2. If branch protection blocks direct commits, MintMCP opens a pull request instead — merge it to finish setup.

When MintMCP ships infrastructure improvements later, an Agent infrastructure needs an update banner appears with a one-click update.

Create the agent​

  1. Click New Agent.
  2. Enter an Agent name (for example, "Bella Billing Agent"). The dialog shows the derived slug and directory name.
  3. Describe what the agent should do. This description seeds the agent's CLAUDE.md instructions, so the more specific you are about its role, tools, and cadence, the better the agent behaves.
  4. Click Create Agent. MintMCP scaffolds the agent directory — agent.yml, CLAUDE.md, progress.md, activity-log.csv, and inbound/ — plus a per-agent workflow. If branch protection requires it, this lands as a pull request you merge before continuing.

The dialog then offers three optional setup sections, each skippable:

  • Claude Credentials — paste an API key or subscription token, or reuse a token from an existing agent.
  • Connect to Slack — give the agent a Slack identity. See Connect a Coworker Agent to Slack.
  • Connect a vMCP — give the agent access to tools from one of your vMCPs.

You can do all of these later from the agent's detail page.

Run the agent​

  1. Click Run on the agent's card or detail page.
  2. Enter a prompt (instructions for this run) and pick a model.
  3. Watch the run under the Tasks tab: it moves from queued to in progress to succeeded or failed.
  4. Click the run to open its detail sheet with the run log and, once the run completes, the full conversation transcript.

Add a schedule​

Add cron expressions (UTC) under triggers.schedule in the agent's agent.yml — edit the file directly, or click Update Agent on the detail page and describe the change. The Triggers card on the Settings tab renders schedules in plain language, for example "daily at 1:00 PM UTC".

triggers:
  schedule: "0 13 * * *"

Troubleshooting​

  • Claude credentials required — the agent has no API key or subscription token yet. Add one under Connectors → Claude Access Token.
  • Needs setup: agent.yml or workflow — the agent directory is missing files or its workflow drifted from the expected configuration. The banner on the detail page offers a one-click fix or Sync Workflow.
  • The agent runs but does nothing useful — that's an instructions problem, not a configuration problem. Refine CLAUDE.md: state the agent's goals, priorities, and what "done" looks like each run.

Next steps​