ACI MCP Server

A Model Context Protocol (MCP) server that gives Claude (or any MCP-compatible AI client) natural-language tools to read and configure a live Cisco ACI fabric through the APIC REST API — with confirmation required before any state-changing action, and structural safety checks that can't be bypassed by confirmation alone.

Built and tested against Cisco's free DevNet "ACI Simulator Always-On" sandbox. Full build write-up: (link to HackerNoon article here once published).

Why this exists

Most AI assistants can explain Cisco ACI's object model. This gives Claude the ability to actually operate one — read fabric state, build a real Tenant → Application Profile → EPG → Bridge Domain → VRF hierarchy, apply contracts between EPGs, and audit the result — through conversation, with every write gated behind explicit confirmation.

Features

• 15 tools spanning fabric visibility, tenant/application management, the full ACI object hierarchy, and policy enforcement via contracts
• Dry-run by default — every state-changing tool describes what it would do and requires a second call with confirm=True to actually apply it
• Unconditional guardrails where they matter — delete_tenant refuses to touch common, infra, or mgmt regardless of confirm
• Pre-flight dependency checks — create_bridge_domain and apply_contract verify their target VRF/contract actually exists before creating a reference to it, rather than silently accepting a dangling one (see CHANGELOG.md for the real bug this fixed)
• A structural audit tool, not just a lister — get_tenant_detail walks an entire tenant's object tree in one call and flags anything incomplete

Tool reference

Tool	Type	Description
list_tenants	Read	List every tenant on the fabric
get_fabric_health	Read	Fabric-wide health score
get_faults	Read	Active faults filtered by severity
get_port_config	Read	EPG static binding + AAEP for a pod/node/interface
get_tenant_detail	Read	Full-subtree audit of a tenant, flags incomplete objects
create_tenant	Write	Create a tenant
delete_tenant	Write	Delete a tenant — hard-refuses common/infra/mgmt
create_application_profile	Write	Create an AP inside a tenant
create_epg	Write	Create an EPG inside an AP, optional BD binding
create_bridge_domain	Write	Create a BD with a VRF (pre-flight checked)
associate_epg_bridge_domain	Write	Bind an existing EPG to an existing BD
create_vrf	Write	Create a VRF (Context) inside a tenant
create_contract	Write	Create a contract + filter, optional port restriction
apply_contract	Write	Apply a contract between provider and consumer EPGs (pre-flight checked)
add_static_path_binding	Write	Bind an EPG to a physical port with a VLAN

All Write tools require confirm=True to actually execute; called without it, they return a description of the intended change instead.

Requirements

• Python 3.10+ (the mcp SDK requires it — 3.9 will fail to install it)
• Access to an APIC controller (a free DevNet sandbox works fine — get current credentials at devnetsandbox.cisco.com, search "ACI Simulator")
• An MCP-compatible client (Claude Code, Claude Desktop, etc.)

Setup

git clone https://github.com/<your-username>/aci-mcp-server.git
cd aci-mcp-server
pip install -r requirements.txt
cp .env.example .env
# edit .env with your real APIC_URL / APIC_USER / APIC_PASSWORD

Sanity check before wiring in an AI client — confirm the server starts cleanly on its own:

python3 aci_mcp_server.py

It should hang silently (waiting on stdio) with no traceback — that's success. Ctrl+C to stop.

Registering with Claude Code

claude mcp add aci-lab --scope user -- python3 /full/path/to/aci_mcp_server.py

If your APIC/environment is only reachable from a remote host (e.g. behind SSH, or inside a container), pass credentials explicitly and route through that instead:

claude mcp add aci-lab --scope user -- ssh user@host docker exec -i \
  -e APIC_URL=https://your-apic \
  -e APIC_USER=admin \
  -e "APIC_PASSWORD=your-password" \
  container-name python3 /path/in/container/aci_mcp_server.py

Start a fresh Claude Code session, run /mcp to confirm aci-lab shows connected with 15 tools, then try:

"List all tenants"

"Check fabric health"

A worked example

docs/testcase_app_to_db.md walks through a complete test case: building a fresh tenant from nothing — VRF, two Bridge Domains, an Application Profile, an App-tier EPG and a DB-tier EPG — then applying a contract that permits only TCP/5432 between them, with the DB tier correctly configured as the provider and the App tier as the consumer.

Design notes

• MCP is a protocol, not an AI feature. This server works unmodified with any MCP-compatible client — Claude, ChatGPT via its Agents SDK, Gemini, or a local model — since nothing in the code is Claude-specific.
• The dry-run/confirm pattern is enforced in code, not by the model's judgment. A write tool called without confirm=True cannot reach APIC — the check happens before any network call, not after.
• Not every guardrail is the same strength on purpose. Most writes are soft-gated (confirm and proceed); deleting a system tenant is hard-gated (no confirmation path exists at all). See delete_tenant.

Security

• .env is git-ignored — never commit real credentials.
• This is built and tested against a free, shared DevNet sandbox. If you point this at a production APIC, review the credential-handling pattern first — storing a real password as a plaintext environment variable passed on a command line (as shown in the SSH example above) is acceptable for a lab, not for production. Use a proper secrets manager instead.

License

MIT

Author

Built by Real Paul — network automation engineer, NetDevOps. More at GitHub and HackerNoon.