Skip to main content

Claude Code

Claude Code is Anthropic's CLI/IDE agent. It auto-detects .mcp.json files at project roots and loads the servers on startup — a perfect fit for the Infrahub MCP server when you're working inside a specific Infrahub consumer repository (IaC, Ansible, Python clients, etc.).

Quick start​

See the Installation guide for the minimal Claude Code configuration snippet. This page covers Claude Code-specific workflows.

Project-scoped setup​

Create .mcp.json at the root of the repository where you want the Infrahub server available:

{
  "mcpServers": {
    "infrahub": {
      "command": "uvx",
      "args": ["infrahub-mcp"],
      "env": {
        "INFRAHUB_ADDRESS": "http://localhost:8000",
        "INFRAHUB_API_TOKEN": "your-api-token"
      }
    }
  }
}

Claude Code loads the server on the next session. Run claude in the project directory and you should see infrahub listed under /mcp.

Keeping the token out of .mcp.json​

.mcp.json is usually committed to your repository, so it should not contain secrets. Instead, keep only the non-secret INFRAHUB_ADDRESS in its env: block and put the token in a .env file (kept out of version control) in the same directory.

.mcp.json (committed):

{
  "mcpServers": {
    "infrahub": {
      "command": "uvx",
      "args": ["infrahub-mcp"],
      "env": {
        "INFRAHUB_ADDRESS": "http://localhost:8000"
      }
    }
  }
}

.env (add it to .gitignore; place it in the directory Claude Code launches from):

INFRAHUB_API_TOKEN=your-token-here
# or, instead of a token:
# INFRAHUB_USERNAME=admin
# INFRAHUB_PASSWORD=infrahub

At server startup the server loads exactly four keys from .env: INFRAHUB_ADDRESS, INFRAHUB_API_TOKEN, INFRAHUB_USERNAME, and INFRAHUB_PASSWORD. Every other key is ignored, including other Infrahub SDK settings such as INFRAHUB_PROXY and INFRAHUB_TLS_INSECURE, and the INFRAHUB_MCP_* server settings (set those in the real environment or the .mcp.json env: block). Values already set in the real environment take precedence, so .env never overrides an explicitly set variable. Set INFRAHUB_MCP_ENV_FILE=/path/to/file to load a different file (~ is expanded), or INFRAHUB_MCP_ENV_FILE= (empty) to disable loading.

Use either a token or a username and password, not both. If .env and the .mcp.json env: block each supply one of the two, the server stops at startup with a message naming the conflict.

In the HTTP token-passthrough and basic-passthrough modes the Infrahub credential comes from the request Authorization header, so a token in .env is ignored; .env still supplies INFRAHUB_ADDRESS.

User-scoped setup​

For always-on access across every project, add the same block to ~/.claude/settings.json instead. The server is spawned once per Claude Code session.

Using the bundled prompt​

Invoke the infrahub_agent system prompt directly:

/infrahub_agent

The prompt teaches Claude the schema-discovery pattern, the session-branch write workflow, and when to use each tool. It dynamically reflects read-only mode — if the server is running with INFRAHUB_MCP_READ_ONLY=true, the prompt tells the model that write paths are unavailable.

CLAUDE.md conventions​

If you're adding the MCP server to a shared repository, document the expected workflow in CLAUDE.md so collaborators' sessions behave consistently. Example snippet:

## Infrahub MCP

This repo has the Infrahub MCP server wired up via `.mcp.json`. Claude should:

1. Read `infrahub://schema` before guessing kind names.
2. Use `search_nodes` for human-entered identifiers.
3. Always call `propose_changes` after writes — never merge yourself.
4. Prefer read-only tools unless the user explicitly asks for a mutation.

Remote server​

For a shared HTTP deployment, replace the stdio block with:

{
  "mcpServers": {
    "infrahub": {
      "transport": "streamable-http",
      "url": "http://mcp.internal:8001/mcp"
    }
  }
}

Combine with token pass-through or OIDC for multi-user deployments.

Troubleshooting​

SymptomFix
.mcp.json not picked upClaude Code requires the file at the project root. Confirm with ls .mcp.json in the directory where you launched Claude.
"Unknown tool" errorsCache stale; restart Claude Code to re-fetch tools/list.
Permissions dialog on every callPre-approve write tools in .claude/settings.json or use the /allow command.