Back to Guides

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

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 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:

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:

# 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:

/plugin marketplace add tractorjuice/arckit-claude

Step 2: Install the plugin

/plugin

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

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 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:

{
  "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):

{
  "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 or the Google Cloud Console
  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:
# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export GOOGLE_API_KEY="your-api-key-here"
  1. 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
  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:
# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export DATA_COMMONS_API_KEY="your-api-key-here"
  1. 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:

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

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

Configuration Reference

The plugin's bundled MCP configuration (.mcp.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

/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.

Resources