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

> Configure ArcKit easily with this complete setup guide. Install the plugin, restart Claude Code, and set API keys for AI architecture governance. Get started today!

- Repository: [tractorjuice/arc-kit](https://github.com/tractorjuice/arc-kit)
- Tags: how-to-guide
- Published: 2026-04-19

---

**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`](https://github.com/tractorjuice/arc-kit/blob/main/README.md) (lines 38-44), run the following commands:

```text
/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`](https://github.com/tractorjuice/arc-kit/blob/main/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:

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

```

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

```bash
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`](https://github.com/tractorjuice/arc-kit/blob/main/README.md) (lines 58-66) and creates the necessary project structure including the [`.mcp.json`](https://github.com/tractorjuice/arc-kit/blob/main/.mcp.json) configuration file. The implementation resides in [`src/arckit_cli/__init__.py`](https://github.com/tractorjuice/arc-kit/blob/main/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`](https://github.com/tractorjuice/arc-kit/blob/main/.mcp.json) (lines 1-13) includes AWS Knowledge and Microsoft Learn servers that work without API keys:

```json
{
  "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**:

```bash
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`](https://github.com/tractorjuice/arc-kit/blob/main/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:

```text
/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`](https://github.com/tractorjuice/arc-kit/blob/main/docs/guides/pinecone-mcp.md) (lines 1-33):

1. Create a project-local [`.mcp.json`](https://github.com/tractorjuice/arc-kit/blob/main/.mcp.json) file (outside the bundled configuration). The plugin merges both files automatically.

2. Add the Pinecone configuration:

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

```

3. Set the environment variable:

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

```text
/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`](https://github.com/tractorjuice/arc-kit/blob/main/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`](https://github.com/tractorjuice/arc-kit/blob/main/.claude/settings.json) with `enabledPlugins` entry (see [`docs/guides/mcp-servers.md`](https://github.com/tractorjuice/arc-kit/blob/main/docs/guides/mcp-servers.md) lines 64-81) |
| Pinecone search does nothing | [`.mcp.json`](https://github.com/tractorjuice/arc-kit/blob/main/.mcp.json) entry missing or API key not set | Add Pinecone entry to project-local [`.mcp.json`](https://github.com/tractorjuice/arc-kit/blob/main/.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`](https://github.com/tractorjuice/arc-kit/blob/main/.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`](https://github.com/tractorjuice/arc-kit/blob/main/src/arckit_cli/__init__.py).

### Where does ArcKit store MCP configuration?

The bundled MCP configuration lives in [`.mcp.json`](https://github.com/tractorjuice/arc-kit/blob/main/.mcp.json) at the repository root. For project-specific additions, create a local [`.mcp.json`](https://github.com/tractorjuice/arc-kit/blob/main/.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`](https://github.com/tractorjuice/arc-kit/blob/main/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.