How to Configure ArcKit: Complete Setup Guide for AI Architecture Governance

Install the ArcKit plugin via /plugin marketplace add tractorjuice/arc-kit, restart Claude Code, and optionally set GOOGLE_API_KEY and DATA_COMMONS_API_KEY environment variables to enable cloud-research MCP servers.

ArcKit is an open-source Enterprise Architecture Governance & Vendor Procurement Toolkit that works across multiple AI assistants including Claude Code, Gemini CLI, GitHub Copilot, and Codex/OpenCode CLI. This guide covers how to configure arc-kit from the tractorjuice/arc-kit repository, including plugin installation, MCP server setup, and optional API key configuration.

Installing the ArcKit Plugin in Claude Code

The primary configuration method for Claude Code users is through the plugin marketplace. According to the repository's README.md (lines 38-44), run the following commands:

/plugin marketplace add tractorjuice/arc-kit
/plugin

The first command adds the marketplace entry, while the second opens the plugin manager where you can install "arckit". After installation, restart Claude Code so the plugin can load its hooks and MCP configuration. The restart is required for the Model Context Protocol (MCP) servers to initialize properly, as noted in docs/guides/mcp-servers.md (lines 49-53).

Initialising a Project for Non-Claude Assistants

For Gemini CLI, Codex CLI, OpenCode CLI, or GitHub Copilot, configuration starts with the arckit init command. First, install the toolkit:

pip install git+https://github.com/tractorjuice/arc-kit.git

Then initialize a project for your specific assistant (example for Copilot):

arckit init my-project --ai copilot
cd my-project && code .

Replace --ai copilot with --ai gemini, --ai codex, or --ai opencode for other assistants. This scaffolding is documented in README.md (lines 58-66) and creates the necessary project structure including the .mcp.json configuration file. The implementation resides in src/arckit_cli/__init__.py.

Configuring MCP Servers

ArcKit bundles four MCP servers for cloud research and documentation lookup. The default configuration in .mcp.json (lines 1-13) includes AWS Knowledge and Microsoft Learn servers that work without API keys:

{
  "mcpServers": {
    "aws-knowledge": {
      "type": "http",
      "url": "https://knowledge-mcp.global.api.aws"
    },
    "microsoft-learn": {
      "type": "http",
      "url": "https://learn.microsoft.com/api/mcp"
    }
  }
}

Adding Optional API Keys

For full functionality, add API keys for Google Developer Knowledge and Data Commons. Set these environment variables before launching Claude Code:

export GOOGLE_API_KEY="your-google-api-key"
export DATA_COMMONS_API_KEY="your-datacommons-api-key"

The MCP servers guide (lines 38-66) details these steps. After setting variables, restart Claude Code to pick up the new configuration (lines 84-88). The user-configurable fields are declared in arckit-claude/.claude-plugin/plugin.json, which handles the substitution of ${GOOGLE_API_KEY} and ${DATA_COMMONS_API_KEY} into MCP headers.

Verifying MCP Configuration

Open the plugin manager (/plugin) → Installed → ArcKit. You should see 68 slash commands, 6 agents, 1 skill, and 4 hooks. Missing API keys generate harmless warnings that disappear once environment variables are set (lines 71-78).

Test the configuration with a bundled server command:

/arckit:aws-research "What is Amazon Aurora?"

If AWS documentation returns, the MCP layer is functioning correctly.

Adding Third-Party MCP Servers

ArcKit supports external MCP servers beyond the bundled set. For example, to add Pinecone for vector search on architecture artifacts, documented in docs/guides/pinecone-mcp.md (lines 1-33):

1. Create a project-local .mcp.json file (outside the bundled configuration). The plugin merges both files automatically.

2. Add the Pinecone configuration:

{
  "mcpServers": {
    "pinecone": {
      "type": "http",
      "url": "https://your-pinecone-endpoint",
      "headers": { "Api-Key": "${PINECONE_API_KEY}" }
    }
  }
}

3. Set the environment variable:

export PINECONE_API_KEY="pine-key-xyz"

4. Restart Claude Code.

Customising Templates

ArcKit stores default document templates in .arckit/templates/. To customise templates for your organisation:

/arckit.customize requirements

This copies the template to .arckit/templates-custom/, where modifications persist across plugin upgrades. All subsequent commands use the customised version automatically (README.md lines 32-38).

Troubleshooting Common Configuration Issues

Symptom	Likely cause	Fix
“Missing environment variables: GOOGLE_API_KEY” in plugin UI	API key not exported before starting Claude	Export GOOGLE_API_KEY and restart Claude Code (see Adding Optional API Keys section)
MCP server not responding	Variable typo or stale token	Verify echo $GOOGLE_API_KEY (or DATA_COMMONS_API_KEY) and restart
No commands appear after plugin install	Plugin not enabled for the repo	Add .claude/settings.json with enabledPlugins entry (see docs/guides/mcp-servers.md lines 64-81)
Pinecone search does nothing	.mcp.json entry missing or API key not set	Add Pinecone entry to project-local .mcp.json and set PINECONE_API_KEY

Summary

• Install the ArcKit plugin via the Claude Code marketplace using /plugin marketplace add tractorjuice/arc-kit and restart to load MCP servers.
• For non-Claude assistants, use pip install followed by arckit init <project> --ai <assistant> to scaffold configuration.
• Configure bundled MCP servers by setting optional GOOGLE_API_KEY and DATA_COMMONS_API_KEY environment variables before launching Claude Code.
• Add third-party MCP servers like Pinecone by creating a project-local .mcp.json file and setting the corresponding API key environment variable.
• Customise document templates using /arckit.customize <template> to persist organisation-specific changes across upgrades.

Frequently Asked Questions

Do I need API keys to use ArcKit?

No. ArcKit works out-of-the-box with AWS Knowledge and Microsoft Learn MCP servers. You only need GOOGLE_API_KEY and DATA_COMMONS_API_KEY if you want to use the Google Developer Knowledge and Data Commons research features.

Can I use ArcKit with assistants other than Claude Code?

Yes. ArcKit supports Gemini CLI, GitHub Copilot, Codex CLI, and OpenCode CLI. Use the arckit init command with the --ai flag to scaffold projects for these assistants, as implemented in src/arckit_cli/__init__.py.

Where does ArcKit store MCP configuration?

The bundled MCP configuration lives in .mcp.json at the repository root. For project-specific additions, create a local .mcp.json in your working directory—the plugin merges both files automatically. Environment variables for API keys are referenced using ${VAR_NAME} syntax within these JSON files, as declared in arckit-claude/.claude-plugin/plugin.json.

How do I update ArcKit configuration after changing API keys?

Restart Claude Code after setting or changing any API key environment variables. The plugin loads MCP configuration at startup, so changes to GOOGLE_API_KEY, DATA_COMMONS_API_KEY, or PINECONE_API_KEY require a restart to take effect.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}