Skip to main content

Configure a Coworker Agent

Adjust an agent's model, triggers, tools, secrets, and sandbox from its detail page in MintMCP or by editing agent.yml directly.

The agent.yml file in the agent's directory is the source of truth. The Settings tab edits it for you, the Update Agent button lets you describe a change in plain language and review it as a proposed change, and editing the file in git works too — all three end up in the same place. MintMCP validates the configuration and surfaces warnings on the agent's page (for example, a secret referenced but never declared), each with a one-click fix.

Harness and model​

The Harness card on the Settings tab picks the runtime that drives the agent.

HarnessProviderModelsCredential
Claude AgentAnthropic APIClaude Opus, Sonnet, Haiku, or FableAnthropic API key, or a Claude subscription token from claude setup-token
Claude AgentAmazon BedrockClaude models via BedrockBedrock API key, region, and model ID
Claude AgentClaude-compatible APIAny compatible model (e.g. GLM-5.2 via Fireworks)API key for your provider
CodexOpenAIGPT-5.5 (default) and other OpenAI modelsOpenAI API key or Codex auth file

Claude Agent and Codex harnesses support a thinking-effort setting (low, medium, high, or xhigh — default high) to trade depth for speed.

Triggers​

triggers:
  schedule:
    - "0 13 * * *"      # daily at 1:00 PM UTC
  workflow_dispatch: true
TriggerConfiguration
ScheduleOne or more cron expressions under triggers.schedule, evaluated in UTC
ManualThe Run button collects a prompt and model; add custom inputs under triggers.workflow_dispatch_inputs
Slack mentionSet up on the Connectors tab — see Connect a Coworker Agent to Slack

By default, messages from other bots don't trigger the agent. To let a specific bot (like another agent) trigger this one, list its bot ID under triggers.slack_allowed_bot_ids.

Setting concurrency: true keeps one run per Slack conversation, so a burst of mentions in a thread doesn't fan out into parallel runs.

Runtime limits​

Runs default to a 20-minute timeout. Raise or lower it with runtime.timeout_minutes, and cap the number of agent turns per run with runtime.max_turns — generous enough limits let an agent finish one task well, while tight limits keep scheduled runs cheap.

Tools and connectors​

Connect a vMCP from the Connectors tab to give the agent access to your MCP tools. MintMCP mints a dedicated API key for the agent, adds the server to agent.yml, and adds its tools to the agent's allowlist — every call the agent makes flows through the gateway under the agent's own identity, so it shows up in your audit log like any other gateway traffic.

allowed_tools is a real allowlist: a tool not in the list is not callable, even if its server is configured. Trim it to just what the agent needs.

You can also declare MCP servers directly in agent.yml (stdio commands or HTTP endpoints, with {{secrets.KEY}} templating for credentials). Direct servers don't pass through the gateway, so prefer vMCP connections when you want gateway-level audit and rules.

Secrets​

Secrets are stored in MintMCP (encrypted at rest) and injected at run time — never written into agent.yml.

ScopeFieldUse for
Agentsecret_keysCredentials specific to one agent, like its vMCP key
Repositoryrepo_secret_keysCredentials shared by all agents in the repo, like a Claude token

The Secrets tab shows every declared secret with its set/unset status and lets you add or replace values. Reference secrets in agent.yml as {{secrets.MY_KEY}} — the validator rejects hardcoded credentials, so a pasted API key never lands in git.

For secrets the agent shouldn't see in plaintext, configure secret brokering per secret with a domain allowlist: the run gets a placeholder, and MintMCP injects the real value only into requests to the allowed domains.

Sandbox​

Each run executes in a sandbox with restricted network egress. GitHub, Anthropic, and package-registry endpoints are reachable by default; add anything else the agent needs under sandbox.allowed_domains:

sandbox:
  enabled: true
  allowed_domains:
    - api.stripe.com

The allowlist only adds domains — you can't remove the defaults the agent needs to function. See Coworker Agents security for what the sandbox does and doesn't guarantee.

Workspaces​

The Workspaces tab checks additional repositories out alongside the agent's own, which suits agents whose definition lives in one repo but whose work targets others. Click Add workspace and enter a name and the repository's owner/repo. MintMCP detects access automatically: repositories the GitHub App can reach are checked out with authentication, and public repositories work without it. The agent's definition repository is marked Primary.

Sub-agents and skills​

  • Sub-agents — Markdown files in the agent directory's .claude/agents/ folder define focused helpers the agent can delegate to. They appear on the Sub-agents tab.
  • Skills — reusable automations shared across agents in the repository, invoked like slash commands. Browse your organization's skills on the Skills page under Coworker Agents.

Example agent.yml​

name: Bella Billing Agent
harness: claude
runtime:
  model: opus
  timeout_minutes: 30
triggers:
  schedule: "0 13 * * *"
  workflow_dispatch: true
concurrency: true
secret_keys:
  - VMCP_KEY_BILLING
allowed_tools:
  - stripe_list_invoices
  - stripe_get_customer
sandbox:
  enabled: true
  allowed_domains:
    - api.stripe.com
hooks:
  mintmcp_monitor: true

The mintmcp_monitor hook is on by default and worth keeping — it streams the session into Agent Monitor so you can watch what the agent does turn by turn.

Next steps​