axm-mcp 0.6.0

axm-mcp — MCP server for the axm-protocols ecosystem

Features

• 🔌 Auto-discovery — Finds all axm.tools entry points from installed packages
• 🛠️ MCP bridge — Exposes discovered tools as Model Context Protocol callables
• 🔎 Compact facade — Four meta-tools (axm_search / axm_describe / axm_call / axm_capabilities) index the full catalog and keep the tools/list payload small (toggle via AXM_MCP_FACADE)
• ✅ Verify — One-shot project quality check: audit + init check + AST enrichment
• 🌐 Web fetch — Anti-bot web page fetching via Scrapling (basic / dynamic / stealth)
• 📋 List tools — Built-in list_tools meta-tool to enumerate all available tools and their descriptions

Installation

Connect the server to your MCP client (Claude Code, IDE…) in one command — no manual install, uvx fetches the latest version on demand:

claude mcp add --scope user axm-mcp -- uvx --python 3.12 --from "axm-mcp[all]@latest" axm-mcp

--scope user installs it globally (available in every session). Drop it to enable AXM per-project instead — the server then loads only in the directory where you run the command.

Prefer editing .mcp.json by hand? Add:

{
  "mcpServers": {
    "axm-mcp": {
      "command": "uvx",
      "args": ["--python", "3.12", "--from", "axm-mcp[all]@latest", "axm-mcp"]
    }
  }
}

The [all] extra is what pulls in the actual tools (audit, ast_*, git_commit, …); the bare axm-mcp package is only the server shell. See the Quick Start for the full walkthrough and why each flag matters.

Server Modes

axm-mcp supports two transport modes. stdio (above) is the simple default — one server process per conversation, works everywhere. HTTP is an advanced option for running a single shared persistent server.

For the HTTP setup, see Migrate to HTTP Transport.

CLI Commands

The HTTP transport exposes a /health endpoint returning {"status": "ok", "tools_count": N}. Port can also be set via the AXM_MCP_PORT environment variable.

Service Management (macOS)

AXM supervisors discover the HTTP service through the package's axm.daemons entry point. The published launch plan preserves AXM_PROFILE and an explicit AXM_MCP_PORT, so the supervised process and its health probe use the same profile-scoped PID file and port.

axm-mcp can also run as a persistent background service managed by launchd:

# Install and start the service
axm-mcp install

# Remove the service
axm-mcp uninstall

install locates the axm-mcp binary, generates a launchd plist, and loads it via launchctl. uninstall unloads the service and removes the plist file.

MCP Tools

By default (AXM_MCP_FACADE=1) the server keeps the tools/list payload small by exposing a compact facade — four meta-tools that index the full catalog — plus a hot path of frequently-used tools that opt in via expose_directly, and the always-on built-ins (verify, web_fetch, list_tools). Every other discovered tool stays reachable through axm_call. Set AXM_MCP_FACADE=0 to fall back to the legacy behaviour (register every discovered tool directly).

To trim a shared server's surface, set AXM_DISABLE_TOOLS to a comma-separated list of tool names or glob patterns to exclude at discovery time (e.g. AXM_DISABLE_TOOLS=bib_*,ticket_*,ast_dead_code). See the CLI reference for the full environment-variable table.

Development

This package is part of the axm-forge workspace.

git clone https://github.com/axm-protocols/axm-forge.git
cd axm-forge
uv sync --all-groups
uv run --package axm-mcp --directory packages/axm-mcp pytest -x -q

License

Apache-2.0 — © 2026 Gabriel Jarry