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.

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.