Claude Code MCP Sidecar — AIWG Tooling Layer

Claude Code MCP Sidecar — AIWG Tooling Layer

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.

Connect the AIWG MCP server to Claude Code for structured artifact management and workflow tools.

This is a tooling layer, not a permission workaround. Claude Code already supports the dangerously-skip-permissions option for unrestricted filesystem access. The MCP sidecar adds a complementary layer: structured AIWG tools for artifact management, template rendering, and workflow execution.

Two-Layer Model

LayerFlag / ToolControls
Permissionthe dangerously-skip-permissions optionFilesystem access, tool approval
ToolingMCP sidecar (the agent-owned mcp operation)AIWG artifact tools, workflows, templates

Both layers are independent. You can use either or both:

ConfigurationUse Case
Permission onlyDirect file editing with full access
Sidecar onlyAIWG tools with standard permission prompts
Both (recommended)Full AIWG experience — unrestricted access + structured tooling

Architecture

Claude Code (host)
  ├── Conversation, code editing
  ├── the dangerously-skip-permissions option (permission layer)
  └── MCP connection (tooling layer)
        └── AIWG MCP Server (sidecar)
              ├── discover / command-run
              ├── artifact-read / artifact-write
              ├── template-render
              └── agent-list

Setup

Step 1: Install MCP Configuration

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

This creates or merges into `.claude/settings.local.json`:

{
  "mcpServers": {
    "aiwg": {
      "command": "aiwg",
      "args": ["mcp", "serve"],
      "env": {
        "AIWG_ROOT": "~/.local/share/ai-writing-guide"
      }
    }
  }
}

Step 2: Verify

Restart Claude Code, then ask: "What AIWG MCP tools are available?"

Claude Code should list the AIWG core tools.

Step 3: Use Both Layers Together

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

Claude Code starts with the dangerously-skip-permissions option and has AIWG MCP tools available via the sidecar simultaneously.

What the Sidecar Adds

Without the sidecar, Claude Code can read and write files directly but has no structured interface to AIWG's artifact system. With it:

ToolPurpose
`discover`Find AIWG skills, commands, rules, agents, and Flow wrapper skills
`command-run`Invoke allow-listed AIWG CLI commands programmatically
`artifact-read`Structured read from `.aiwg/` with schema validation
`artifact-write`Structured write to `.aiwg/` with schema validation
`template-render`Fill AIWG templates with project context
`agent-list`Discover and invoke specialized agents by role

`workflow-run` has been removed. Use `command-run` for general AIWG CLI execution. For first-class YAML Flow tools, start the server with `AIWG_MCP_TOOLSETS=flows` and allow `flow-list`, `flow-show`, and `flow-run`. For Mission tools, use `AIWG_MCP_TOOLSETS=missions` and allow `mission-guide`, `mission-dispatch`, and `mission-status`.

Example Workflows

SDLC Accelerate with Full Stack

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

Claude Code runs with full filesystem access and can call AIWG MCP tools for structured artifact management.

Agent Loop with Sidecar

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

The agent loop agent can use `artifact-read` to check existing requirements and `artifact-write` to update test documentation alongside its direct file edits.

Artifact-Driven Workflow

Without the dangerous option, the sidecar still provides structured access:

# Start Claude Code normally, with AIWG tools available
claude .

Then ask Claude Code to:

Create a Software Architecture Document for this project using AIWG templates
and save it to .aiwg/architecture/.

Claude Code calls `template-render` to generate the document and `artifact-write` to persist it with schema validation.

Verification Checklist

CheckActionExpected
MCP connectionAsk "list AIWG tools"AIWG core tools listed
Artifact writeAsk to create an ADRFile appears in `.aiwg/architecture/`
Permission layerEdit a file outside `.aiwg/`No permission prompt (with the dangerous option)
CombinedRun a workflow that reads requirements and writes codeBoth layers work together

Troubleshooting

AIWG tools not visible in Claude Code:

  • Check `.claude/settings.local.json` has the `mcpServers.aiwg` entry
  • Verify the agent-owned mcp operation runs successfully standalone: the agent-owned mcp operation
  • Restart Claude Code after config changes

Permission prompts still appearing with the sidecar:

  • The sidecar does not grant filesystem permissions — that is the the dangerously-skip-permissions option flag
  • Use the dangerously-skip-permissions option (via the dangerous option shorthand) for unrestricted filesystem access

Artifacts not appearing in `.aiwg/`:

  • Ensure AIWG is initialized in the project: the agent-owned use operation
  • Check that `artifact-write` is in the tool whitelist
  • Verify the working directory matches the project root