# ArcKit Plugin Setup Guide

> **Guide Origin**: Official | **ArcKit Version**: [VERSION]

This guide covers installing the ArcKit plugin, configuring MCP servers, and complementary plugins that enhance architecture workflows.

---

## Installing the ArcKit Plugin

### Prerequisites

- **Claude Code** v2.1.287 or later (or **Claude Cowork** desktop app)
- **Bash** shell (for helper scripts)

### Step 0: Make sure Claude Code is up to date

```bash
claude install latest
claude --version
```

`claude install` accepts `stable`, `latest`, or a specific version (e.g. `claude install 2.1.287`). If you don't have the `claude` CLI yet, follow the [official Claude Code install guide](https://docs.claude.com/en/docs/claude-code/quickstart) first.

### Optional: Long-session prompt cache (Claude Code v2.1.108+)

Long ArcKit workflows -- requirements -> data-model -> components -> stories, or any chain that re-reads the same templates, principles, and project artifacts -- benefit from the 1-hour prompt cache TTL introduced in Claude Code v2.1.108. The default 5-minute TTL expires between commands when you pause to review output, file the next prompt, or step away.

Set the env var before launching Claude:

```bash
export ENABLE_PROMPT_CACHING_1H=1
claude
```

Recommended for: overnight `autoresearch` runs, multi-command workflows (`/arckit:requirements` -> `/arckit:data-model` -> `/arckit:components`), and research agents that re-read large project context. Verify cache uplift in your Anthropic billing dashboard (`cache_read_input_tokens` should grow as a fraction of input tokens).

### Optional: MCP per-request timeout (Claude Code v2.1.142+)

The three bundled cloud-research MCP servers (`aws-knowledge`, `microsoft-learn`, `google-developer-knowledge`) are remote HTTP servers reached from your machine. Behind corporate proxies, TLS-inspecting gateways, or slow links, individual fetches inside a single tool call can exceed Claude Code's default per-request timeout — surfacing as `MCP tool call failed: timeout` in the middle of a long `/arckit:aws-research`, `/arckit:azure-research`, or `/arckit:gcp-research` run.

Claude Code v2.1.142 made `MCP_TOOL_TIMEOUT` honour the per-request fetch timeout for remote servers (previously it only governed initial connect). Raise it for cloud-research sessions on slow networks:

```bash
# 5-minute per-request timeout (default is 60s)
export MCP_TOOL_TIMEOUT=300000
claude
```

The value is milliseconds. Recommended for: corporate networks with TLS-inspecting proxies, VPN-tunnelled connections, and large-scope research prompts that trigger many `microsoft_docs_fetch` / `aws___read_documentation` / `get_document` calls in sequence. On a healthy direct connection the default is fine — only set this when you see timeout failures.

> **Don't set a sub-second timeout.** As of Claude Code v2.1.162, a per-server `timeout` below `1000` ms is ignored (it falls back to `MCP_TOOL_TIMEOUT` or the default) rather than being floored to a 1-second watchdog that aborted every call. ArcKit ships no sub-1000 ms timeouts, so this is reassurance only — but if you hand-edit a server's `timeout`, keep it ≥ `1000`.

**Slow calls now background themselves (Claude Code v2.1.212+).** An MCP tool call still running after 2 minutes moves to the background automatically, so the session stays usable instead of blocking. Tune the threshold — or turn the behaviour off — with `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`. This works *with* a raised `MCP_TOOL_TIMEOUT` rather than against it: the timeout still bounds how long the call may take, while auto-backgrounding removes the cost of waiting for it. On v2.1.212+ a generous `MCP_TOOL_TIMEOUT` is cheaper than it used to be.

**Per-server timeouts are honoured again (Claude Code v2.1.206+).** A per-server `request_timeout_ms` set in `.mcp.json` or passed via `--mcp-config` was previously ignored, so long-running calls timed out at the 60-second default no matter what the server config said. If you hand-tuned a per-server value before v2.1.206 and concluded it did nothing, retest it — it now applies.

### Step 1: Add the marketplace

In Claude Code, run:

```text
/plugin marketplace add tractorjuice/arckit-claude
```

### Step 2: Install the plugin

```text
/plugin
```

Go to the **Discover** tab, find **arckit**, and install it. Or via CLI:

```bash
claude plugin install arckit@arckit-claude
```

### Step 3: Restart Claude Code

The plugin loads MCP servers and hooks at startup. **A restart is required** after first installation.

### Verifying installation

After restart, open the plugin manager (`/plugin`) and navigate to **Installed**. You should see:

- **Commands**: ArcKit slash commands
- **Agents**: Autonomous research agents
- **Skills**: Reference skills (Wardley, Mermaid, PlantUML, workflow, build harness)
- **Hooks**: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse

> **Tip**: You may see 2 MCP errors about missing API keys for Google and Data Commons. These are harmless — see [Servers Requiring API Keys](#servers-requiring-api-keys) below.

> **Confirm what's enabled from the CLI** (Claude Code v2.1.163+): `/plugin list --enabled` lists the active plugins. Handy because the community overlays (`arckit-uae`, `arckit-fr`, `arckit-au`, …) ship `defaultEnabled: false` — if an overlay's `/arckit:*` commands aren't showing up, it's almost always because it wasn't enabled. Use `/plugin list --disabled` to see what's installed but off.

### Auto-enabling for team repos

To have the plugin auto-enable for anyone who opens your repo, add `.claude/settings.json`:

```json
{
  "extraKnownMarketplaces": {
    "arckit-claude": {
      "source": {
        "source": "github",
        "repo": "tractorjuice/arckit-claude"
      }
    }
  },
  "enabledPlugins": {
    "arckit@arckit-claude": true
  }
}
```

---

## MCP Servers

ArcKit includes 4 bundled MCP (Model Context Protocol) servers for cloud research, plus support for optional third-party MCPs like Pinecone.

> **Two servers work out of the box** (AWS Knowledge, Microsoft Learn). The other two require free API keys (Google Developer Knowledge, Data Commons). If you don't configure the API keys, you'll see errors in the plugin UI — **these are harmless and all other commands work normally**.

---

## Bundled MCP Servers

| MCP Server | API Key | Used By | Status |
|------------|---------|---------|--------|
| AWS Knowledge | Not required | `/arckit:aws-research` | Works out of the box |
| Microsoft Learn | Not required | `/arckit:azure-research` | Works out of the box |
| Google Developer Knowledge | `GOOGLE_API_KEY` | `/arckit:gcp-research` | Requires setup |
| Data Commons | `DATA_COMMONS_API_KEY` | Data statistics lookups | Requires setup |
| Trello (Atlassian) | None; sign in once through `/mcp` | `/arckit:trello` | Sign-in on first use |

### Approving MCP tool calls

ArcKit doesn't approve MCP tool calls on your behalf. The first time a research command calls a server, Claude Code asks. To stop asking for a server you trust, add it to `permissions.allow` in `.claude/settings.json` (for one project) or `~/.claude/settings.json` (for all of them):

```json
{
  "permissions": {
    "allow": [
      "mcp__plugin_arckit_aws-knowledge",
      "mcp__plugin_arckit_microsoft-learn",
      "mcp__plugin_arckit_google-developer-knowledge",
      "mcp__plugin_arckit_datacommons-mcp"
    ]
  }
}
```

Add `"mcp__plugin_arckit_govreposcrape"` and `"mcp__plugin_arckit_uk-tenders"` only if you're content to send queries to those community-run services without being asked. Until 6.17, a hook approved all six servers automatically.

---

## No-Setup Servers

### AWS Knowledge

Provides access to official AWS documentation, service details, regional availability, and architecture guidance.

- **Type**: HTTP (remote endpoint)
- **Commands**: `/arckit:aws-research`
- **Tools**: `search_documentation`, `read_documentation`, `get_regional_availability`, `list_regions`, `recommend`
- **Setup**: None — works immediately after plugin installation

### Microsoft Learn

Provides access to official Microsoft and Azure documentation, code samples, and architecture guidance.

- **Type**: HTTP (remote endpoint)
- **Commands**: `/arckit:azure-research`
- **Tools**: `microsoft_docs_search`, `microsoft_code_sample_search`, `microsoft_docs_fetch`
- **Setup**: None — works immediately after plugin installation

---

## Servers Requiring API Keys

### Google Developer Knowledge

Provides access to Google Cloud documentation for GCP service research.

- **Type**: HTTP (remote endpoint)
- **Commands**: `/arckit:gcp-research`
- **Tools**: `search_documents`, `get_document`, `batch_get_documents`

**Setup**:

1. Get a free API key from [Google AI Studio](https://aistudio.google.com/apikey) or the [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
2. **Claude Code:** the ArcKit plugin asks for the key when you enable it, as a sensitive setting kept in your system keychain. To add or change it later, open `/plugin`, choose **arckit**, and open its configure screen (or run `claude plugin configure arckit` on Claude Code v2.1.285+). ArcKit passes it to the server in a request header; it isn't written to any file.
3. **Other assistants** (Codex CLI, Gemini CLI, OpenCode, GitHub Copilot, Kimi, Mistral Vibe) read it from the environment instead:

```bash
# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export GOOGLE_API_KEY="your-api-key-here"
```

4. Restart your assistant

### Data Commons

Provides access to public statistical data from Data Commons (demographics, economics, health, environment) for grounding architecture decisions in real-world data.

- **Type**: HTTP (remote endpoint)
- **Commands**: Used by research commands for data lookups
- **Tools**: Various data query tools

**Setup**:

1. Get an API key from [Data Commons](https://datacommons.org)
2. **Claude Code:** the ArcKit plugin asks for the key when you enable it, as a sensitive setting kept in your system keychain. To add or change it later, open `/plugin`, choose **arckit**, and open its configure screen (or run `claude plugin configure arckit` on Claude Code v2.1.285+). ArcKit passes it to the server in a request header; it isn't written to any file.
3. **Other assistants** (Codex CLI, Gemini CLI, OpenCode, GitHub Copilot, Kimi, Mistral Vibe) read it from the environment instead:

```bash
# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export DATA_COMMONS_API_KEY="your-api-key-here"
```

4. Restart your assistant

> **Your keys stay hidden in `claude mcp` output.** Both keyed servers carry their key in an HTTP header (`X-Goog-Api-Key`, `X-API-Key`) via `${GOOGLE_API_KEY}` / `${DATA_COMMONS_API_KEY}`. As of Claude Code v2.1.161, `claude mcp list` / `get` / `add` no longer expand `${VAR}` references and redact credential headers and URL secrets — so inspecting your MCP config (or screen-sharing it) won't leak the keys. Relevant for OFFICIAL-SENSITIVE / regulated deployments. The other four bundled servers are keyless, so there's nothing to redact.

### Managing MCP authentication

For OAuth-backed or interactive MCP servers, use Claude Code's MCP auth
commands instead of editing token files by hand:

```bash
claude mcp login <server-name>
claude mcp logout <server-name>
```

ArcKit's bundled Trello server uses this flow: sign in once through `/mcp`
(or `claude mcp login`). The two keyed servers use plugin settings instead (see
above), and the same `claude mcp` workflow is useful when you add third-party
MCP servers alongside ArcKit. Recent Claude Code releases improved OAuth retries and headless login
flows, so stale browser hand-offs are less likely to leave a server half
configured.

Servers that use a `headersHelper` can also refresh credentials after 401/403
responses. If a helper-backed server works once and then starts failing after a
token expiry, run `claude mcp login <server-name>` again before changing the
ArcKit configuration.

---

## Troubleshooting

### "Missing environment variables" errors in plugin UI

```text
Invalid MCP server config for 'google-developer-knowledge': Missing environment variables: GOOGLE_API_KEY
Invalid MCP server config for 'datacommons-mcp': Missing environment variables: DATA_COMMONS_API_KEY
```

**These errors are harmless.** They mean you haven't configured the optional API keys. All ArcKit commands, agents, hooks, and skills work without them. Only `/arckit:gcp-research` and Data Commons lookups are affected.

**To fix**: Set the environment variables as described above and restart Claude Code.

### MCP server not responding after setup

1. Verify the environment variable is set without printing it: `[ -n "$GOOGLE_API_KEY" ] && echo set || echo unset`
2. Restart Claude Code (MCP servers load at startup)
3. Check the plugin UI — errors should disappear once the key is valid
4. Run `claude mcp list` or `/mcp`. As of Claude Code v2.1.218 a failed server reports its **HTTP status and error text**, so an invalid key shows as a real `401` rather than a bare "failed to connect". The same release warns about config values carrying hidden leading or trailing whitespace — a common cause of a key that looks correct but is rejected.
5. On Amazon Bedrock, Google Vertex AI and Microsoft Foundry — and in any session with telemetry disabled — Claude Code v2.1.246+ tells the model when a configured server failed to connect. Before that the model concluded the server's tools did not exist, so a keyless session on those providers made `/arckit:gcp-research` and Data Commons lookups fail with a confusing "no such tool" instead of a connection error. If you see that symptom, update the client and re-check `/mcp`.

### API key works but commands fail

- **Google**: Ensure the API key has the "Generative Language API" enabled in Google Cloud Console
- **Data Commons**: Ensure the key is active and not rate-limited

---

## Optional Third-Party MCPs

ArcKit also supports integration with third-party MCP servers that are **not bundled** with the plugin. These must be configured per-project in your `.mcp.json`.

| MCP | Purpose | Guide |
|-----|---------|-------|
| Pinecone | Vector search across architecture artifacts and Wardley Mapping knowledge base | [Pinecone MCP Guide](pinecone-mcp.md) |

---

## Configuration Reference

The plugin's bundled MCP configuration (`.mcp.json`):

```json
{
  "mcpServers": {
    "aws-knowledge": {
      "type": "http",
      "url": "https://knowledge-mcp.global.api.aws"
    },
    "microsoft-learn": {
      "type": "http",
      "url": "https://learn.microsoft.com/api/mcp"
    },
    "google-developer-knowledge": {
      "type": "http",
      "url": "https://developerknowledge.googleapis.com/mcp",
      "headers": {
        "X-Goog-Api-Key": "${GOOGLE_API_KEY}"
      }
    },
    "datacommons-mcp": {
      "type": "http",
      "url": "https://api.datacommons.org/mcp",
      "headers": {
        "X-API-Key": "${DATA_COMMONS_API_KEY}"
      }
    }
  }
}
```

> **Note**: You do not need to copy this configuration — it is automatically loaded by the plugin. This is shown for reference only.

---

## Complementary Skills for Architects

Anthropic publishes document skills in the `anthropics/skills` marketplace that pair well with ArcKit. These skills let Claude produce polished, client-ready deliverables directly from ArcKit's Markdown artifacts.

### Installing the document skills

```text
/plugin marketplace add anthropics/skills
/plugin
```

Navigate to **Discover** > **anthropic-agent-skills** > **document-skills** and install.

### Available document skills

| Skill | What it does | Architecture use case |
|-------|-------------|----------------------|
| **PDF** (`/pdf`) | Create and edit PDF documents | Export requirements, risk registers, or business cases as formatted PDFs for stakeholder review |
| **DOCX** (`/docx`) | Create and edit Word documents | Produce editable architecture documents for governance boards that require Word format |
| **PPTX** (`/pptx`) | Create and edit PowerPoint presentations | Turn `/arckit:presentation` output or architecture summaries into slide decks for steering committees |
| **XLSX** (`/xlsx`) | Create and edit Excel spreadsheets | Export evaluation matrices, risk scores, or FinOps data into spreadsheets for analysis |

### Example workflows

**Architecture board submission**:

1. Run `/arckit:sobc` to generate a Strategic Outline Business Case
2. Use `/docx` to convert it into a branded Word document with your organisation's template
3. Use `/pptx` to create an executive summary deck from the key findings

**Vendor evaluation pack**:

1. Run `/arckit:evaluate` to score vendors
2. Use `/xlsx` to export the evaluation matrix as a spreadsheet
3. Use `/pdf` to create a sealed PDF for procurement records

**Stakeholder briefing**:

1. Run `/arckit:stakeholders` and `/arckit:requirements`
2. Use `/pptx` to build a slide deck covering stakeholder map, goals, and top-level requirements
3. Share with project sponsors for sign-off

> **Note**: The document skills are maintained by Anthropic in a separate marketplace (`anthropics/skills`). They are not part of the ArcKit plugin but complement it well. They work in both Claude Code and Claude Cowork.

For detailed workflows and real-world examples, see the [Architecture Productivity Guide](productivity.md).

---

## Resources

- [AWS Knowledge MCP](https://awslabs.github.io/mcp/servers/aws-knowledge-mcp-server) — AWS documentation server
- [Microsoft Learn MCP](https://learn.microsoft.com/api/mcp) — Azure documentation server
- [Google Developer Knowledge MCP](https://developerknowledge.googleapis.com/mcp) — Google Cloud documentation server
- [Data Commons](https://datacommons.org) — Public statistical data
- [Model Context Protocol](https://modelcontextprotocol.io/) — MCP specification
- [Anthropic Skills](https://github.com/anthropics/skills) — Document skills (PDF, DOCX, PPTX, XLSX)
- [Claude Plugins Directory](https://claude.com/plugins) — Browse all available plugins