acex-mcp

ACE-X MCP Server

A Model Context Protocol server that gives AI assistants read-only access to ACE-X: the network devices it manages, the configuration each is intended to have, and the configuration snapshots actually collected from them.

It holds no data and no credentials of its own. Every tool is a call to the ACE-X API made as the caller, so the backend authorizes each read against that user's own permissions.

Installation

pip install acex-mcp

Tools

All tools are read-only. Start with find_nodes — the node_id it returns is what every other tool takes.

get_desired_config and get_observed_config take a section argument that keeps only matching configuration blocks, so a question about one interface does not pull a three-thousand-line config into the model's context.

Resources and prompts

Prompts: explain_config_change, assess_config_risk, assess_config_alignment — each takes a diff and an optional context.

Configuration

Only the backend URL is required. OIDC settings are discovered at startup from the backend's public /api/v1/auth/config, so authentication is configured in one place — the backend — and never duplicated here.

Authentication

The two transports authenticate differently, because only one of them has an inbound request to take a token from.

HTTP — the server verifies the incoming bearer token against the backend's OIDC issuer, then forwards that same token to the ACE-X API on every tool call. Inbound verification is not a second layer of protection over the data (the backend authorizes every read regardless); it is what lets an external client discover it must log in, makes an expired token fail once at the boundary instead of becoming a series of tool errors, and identifies the caller in logs.

stdio — there is no inbound request, so the process authenticates as the user through acex_client: ACEX_CLIENT_ID + ACEX_CLIENT_SECRET for a service identity, or an interactive browser login whose token is cached on disk.

If the backend reports authentication disabled, this server also runs without it, so a Keycloak-less development stack works.

Usage

Running the server

python3 -m acex_mcp

Or via the console script, which does exactly the same thing:

acex-mcp

The Docker Compose stack builds and wires this automatically; the backend reaches it at ACEX_AI_OPS_MCP_SERVER_URL=http://mcp-server:8000/mcp.

Configuration for Claude Desktop

Add to your claude_desktop_config.json. stdio is required — Claude Desktop spawns the process and talks to it over a pipe:

{
  "mcpServers": {
    "acex": {
      "command": "acex-mcp",
      "env": {
        "ACEX_MCP_TRANSPORT": "stdio",
        "ACEX_API_URL": "https://acex.example.com"
      }
    }
  }
}

Configuration for VS Code with Cline

Add to your MCP settings, with the same two environment variables:

{
  "mcpServers": {
    "acex": {
      "command": "acex-mcp",
      "args": [],
      "env": {
        "ACEX_MCP_TRANSPORT": "stdio",
        "ACEX_API_URL": "https://acex.example.com"
      }
    }
  }
}

Development

cd mcp
poetry install
ACEX_API_URL=http://localhost:8080 poetry run python -m acex_mcp

Testing

poetry run pytest

tests/test_contract.py guards against the failure that motivated this rewrite: tools that called endpoints which had moved, and described fields the API does not return. It checks that every client method the tools call still exists, and — when a backend is reachable — that every path behind them is still in its OpenAPI spec.

Interactively, with the MCP Inspector:

npx @modelcontextprotocol/inspector acex-mcp

License

AGPL-3.0 - See LICENSE for details.