MCP Profiles

Reusable MCP server profiles

MCP Profiles

Prompt-first procedure: Describe the outcome you want in your agent conversation. The agent should select and load the appropriate AIWG assets, explain material changes, request any needed approval, and report verification evidence. Exact commands and flags appear only in the CLI reference.

Named, ordered subsets of registered MCP servers. Profiles let you launch sessions or inject only the servers relevant to a specific task, without modifying your default provider configuration.

Registry file: `~/.aiwg/mcp-profiles.json`
Schema: `apiVersion: aiwg.io/v1`, `kind: McpProfileRegistry`

Why MCP Profiles

Loading every registered MCP server in every session creates two compounding problems:

Token pressure — MCP servers inject their tool manifests into the context at the start of every session. The measured impact across the built-in presets:

Profile	Servers	Approximate token overhead
`minimal`	none	~0
`dev`	3 servers	~6 K tokens
`ops`	3 servers	~7 K tokens
`incident`	4 servers	~9 K tokens
`full`	all (5+)	~15–21 K tokens

Keeping a heavy code-search server loaded while doing ops work burns budget on every prompt — and the model can't use it for anything relevant.

Über-agent behaviour — when a model sees too many tools, it sometimes reaches for an irrelevant one because it looks plausibly useful. A model that can search the codebase and write to CMDB and read Google Calendar will occasionally try all three on a task that only needed one. Profiles constrain the visible toolset to what the task actually requires.

The preset profiles map directly to common task classes. Run the agent-owned mcp operation once to install them, then use the agent-owned session operation at task start.

`git-gitea` is provider-agnostic: any AIWG provider with MCP injection/support can use it. Some provider guides, especially Hermes, may recommend or require MCP wiring for normal tool access, but that is provider setup guidance, not Git MCP ownership or exclusivity.

Quick Start

Use AIWG to complete this documented outcome: Quick Start
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Preset Profiles

Installed by the agent-owned mcp operation. Do not overwrite existing profiles with the same name.

Name	Servers	Description
`minimal`	(none)	Minimal toolset for smoke tests
`dev`	git-gitea, codeindex-codehound, memory-fortemi	Code editing + git + memory
`ops`	git-gitea, cmdb-itassets, memory-fortemi	Infra + git + CMDB
`research`	memory-fortemi, google-drive, google-calendar	Documentation + memory + calendar
`incident`	git-gitea, cmdb-itassets, memory-fortemi, codeindex-codehound	Incident response
`full`	`__all__`	All registered servers (expands at inject time)

The `git-gitea` entries in `dev`, `ops`, and `incident` are task-profile choices available to all MCP-capable providers. Provider-specific allow/deny rules may restrict dangerous write tools, but they do not make Git MCP provider-specific.

Profiles scope external MCP servers from the registry. AIWG's own server toolsets are controlled separately by `AIWG_MCP_TOOLSETS` or the agent-owned mcp operation. For example, first-class Flow/Mission tools come from `AIWG_MCP_TOOLSETS=flows,missions`, not from the `minimal/dev/ops` profile presets. Keep the two boundaries separate: profiles decide which servers are visible; toolsets decide which optional AIWG tools that one server registers.

Profile Management

Create a profile

Use AIWG to complete this documented outcome: Create a profile
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Server names must exist in the registry (the agent-owned mcp operation). Use the special sentinel `__all__` to expand to all registered servers at inject time.

Use AIWG to complete this documented outcome: Server names must exist in the registry (the agent-owned mcp operation list). Use the special sentinel __all__ to expand to all registered servers at inject time.
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Inspect profiles

Use AIWG to complete this documented outcome: Inspect profiles
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Edit a profile

Use AIWG to complete this documented outcome: Edit a profile
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Remove a profile

Use AIWG to complete this documented outcome: Remove a profile
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Import / export

Use AIWG to complete this documented outcome: Import / export
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Importing merges profiles: existing profiles are updated, new profiles are added. Invalid names are skipped silently.

Using Profiles in Sessions

Ephemeral (default)

The provider's default config is not modified. A temp config is written for the duration of the session.

Use AIWG to complete this documented outcome: The provider's default config is not modified. A temp config is written for the duration of the session.
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

For Claude: the temp config is passed via `the mcp-config option <path>`. For Codex: a per-profile runtime home is set up instead (see Codex Profiles).

Persistent

Writes the profile's servers into the provider's default config permanently.

Use AIWG to complete this documented outcome: Writes the profile's servers into the provider's default config permanently.
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Ephemeral inject (direct)

Use AIWG to complete this documented outcome: Ephemeral inject (direct)
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Provider Support

Profile-aware sessions work differently per provider. AIWG handles the differences behind the scenes — the agent-owned session operation produces the right behaviour for the active provider.

Provider	Support level	Mechanism
Claude Code	Native	Ephemeral JSON config passed via `claude the mcp-config option <tmp>`. Default config unchanged.
Codex	Emulated	Per-profile runtime home (`HOME=~/.codex/roles-runtime/<profile>/`). OAuth tokens isolated per profile. See Codex Profiles.
Cursor	Native	Standalone `.cursor/mcp.json` written ephemerally or persistently.
OpenCode	Native	Config file injection via provider adapter.
Windsurf	Native	Config file injection via provider adapter.
Factory	Native	Config file injection via provider adapter.
Warp	Degraded	Warp does not support file-based MCP config switching. the agent-owned session operation for Warp prints setup instructions and the exact server list to configure via Warp's UI (Settings → AI → MCP Servers).
GitHub Copilot	Degraded	Copilot MCP configuration is managed through VS Code settings. AIWG generates the correct `mcp` block and prints instructions for manual insertion.
OpenClaw	Native	Config injection to `~/.openclaw/` profile directory.

Ephemeral vs persistent

By default, the agent-owned session operation uses ephemeral mode — a temporary config is created for the session duration and the provider's default config is never modified. When the session ends, the temp file is deleted.

Use the persist option to write the profile's servers into the provider's default config permanently:

Use AIWG to complete this documented outcome: Use the persist option to write the profile's servers into the provider's default config permanently
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Warp and Copilot do not support ephemeral mode — the persist option is implicit, and AIWG prints what to copy into the UI rather than modifying config files.

Provider Overrides

Profiles can carry per-provider tool allow/deny lists. These restrict which tools from a server are exposed to a specific provider without affecting other providers.

Structure

{
  "name": "dev",
  "servers": ["git-gitea", "memory-fortemi"],
  "providerOverrides": {
    "codex": {
      "toolDeny": ["git-gitea__delete_*", "git-gitea__actions_config_write"],
      "toolAllow": []
    }
  }
}

`toolDeny` — glob patterns of tool names to block for this provider. `toolAllow` — if non-empty, only these tools are exposed (allowlist mode). Takes precedence over `toolDeny`.

Tool name format: `<server-name>__<tool-name>`, e.g. `git-gitea__delete_branch`. Glob patterns are supported: `git-gitea__delete_*` blocks all delete operations.

The `dev` preset and Codex

The built-in `dev` preset ships with a Codex override that blocks destructive Gitea operations. This prevents accidental branch/repo deletion when running Codex against a shared Gitea instance:

"providerOverrides": {
  "codex": {
    "toolDeny": ["git-gitea__delete_*", "git-gitea__actions_config_write"]
  }
}

Setting overrides via CLI

Provider overrides are not yet editable via the agent-owned mcp operation. Edit `~/.aiwg/mcp-profiles.json` directly or use import/export to update the JSON.

Registry File Format

`~/.aiwg/mcp-profiles.json`:

{
  "apiVersion": "aiwg.io/v1",
  "kind": "McpProfileRegistry",
  "profiles": {
    "dev": {
      "name": "dev",
      "description": "Code editing + git + memory",
      "servers": ["git-gitea", "codeindex-codehound", "memory-fortemi"],
      "providerOverrides": {
        "codex": {
          "toolDeny": ["git-gitea__delete_*", "git-gitea__actions_config_write"]
        }
      },
      "createdAt": "2026-04-17T00:00:00.000Z",
      "updatedAt": "2026-04-17T00:00:00.000Z"
    }
  }
}

Migrating from sysops Scripts

If you used `roctinam/sysops` shell wrappers (`claude-role.sh` / `codex-role.sh`), the AIWG profile system is the direct replacement. The mental model is identical — named role, scoped MCP servers, isolated auth for Codex — but it's provider-agnostic and managed by AIWG rather than maintained in a separate repo.

Claude

Before	After
`claude-role dev`	the agent-owned session operation
`claude-role ops`	the agent-owned session operation
`claude-role minimal`	the agent-owned session operation

the agent-owned session operation passes the mcp-config option to Claude with an ephemeral config — same mechanism `claude-role.sh` used.

Codex

Before	After
`codex-role dev`	the agent-owned session operation
`codex-role ops -- login`	the agent-owned mcp operation
Manual `~/.codex/roles-runtime/dev/` setup	Handled automatically by AIWG on first run

The runtime home layout (`~/.codex/roles-runtime/<profile>/`) is identical to the sysops implementation, so existing auth tokens in those directories are reused automatically on the first the agent-owned session operation run. No re-authentication needed.

Deprecation timeline

Once the agent-owned session operation is running in your environment, the sysops wrappers can be removed from `.bashrc`. The tab-completion aliases (`alias claude-role=...`) can be replaced with shell aliases pointing to the agent-owned session operation if preferred:

# Optional: keep short aliases
alias cr='the agent-owned session operation the profile option'              # cr dev, cr ops, cr minimal
alias crx='the agent-owned session operation the provider option codex the profile option'  # crx dev, crx ops

MCP Profiles

MCP Profiles

Why MCP Profiles

Quick Start

Preset Profiles

Profile Management

Create a profile

Inspect profiles

Edit a profile

Remove a profile

Import / export

Using Profiles in Sessions

Ephemeral (default)

Persistent

Ephemeral inject (direct)

Provider Support

Ephemeral vs persistent

Provider Overrides

Structure

The `dev` preset and Codex

Setting overrides via CLI

Registry File Format

Migrating from sysops Scripts

Claude

Codex

Deprecation timeline

Further Reading