🧠 Cisco ACI Intelligent Explorer — MCP Server

An AI-powered Model Context Protocol (MCP) server that lets any AI assistant (Claude, Cursor, VS Code Copilot, etc.) query and explore your Cisco ACI fabric in natural language.

---

🌟 What Is This?

This project bridges Cisco ACI (Application Centric Infrastructure) and AI assistants through the Model Context Protocol (MCP). Instead of manually browsing the APIC GUI or writing REST API calls, you can simply ask your AI:

"Which Bridge Domains have Unicast Routing disabled but are still attached to an L3Out?" "Show me all interfaces on node-101 that are DOWN and explain why." "What BGP neighbors are configured on leaf-1 and how many are established?"

The MCP server translates these questions into precise APIC REST API calls and returns structured answers.

---

🏗️ Architecture

┌─────────────────────┐        MCP / SSE          ┌────────────────────────┐
│   AI Client         │ ◄──────────────────────►  │  ACI MCP Server        │
│  (Claude, Cursor,   │     (127.0.0.1:9000)      │  aci_mcp_server.py     │
│   VS Code, etc.)    │                           │                        │
└─────────────────────┘                           │  ┌──────────────────┐  │
                                                  │  │  RAG Engine      │  │
                                                  │  │  (Semantic Search│  │
                                                  │  │   over ACI MIM)  │  │
                                                  │  └──────────────────┘  │
                                                  │                        │
                                                  │  ┌──────────────────┐  │
                                                  │  │  APIC REST API   │  │
                                                  │  │  Live Queries    │  │
                                                  │  └──────────────────┘  │
                                                  └────────┬───────────────┘
                                                           │ HTTPS
                                                  ┌────────▼───────────────┐
                                                  │   Cisco APIC           │
                                                  │   (your fabric)        │
                                                  └────────────────────────┘

---

📁 Project Structure

cisco-aci-mcp-server/
│
├── aci_mcp_server.py          ← 🚀 Main MCP Server (run this daily)
├── apic_config.py             ← 🔑 APIC credentials (configure before first use)
├── requirements.txt           ← 📦 Python dependencies (pip install -r requirements.txt)
│
├── mcp_config/
│   ├── aci_rag_dataset.json   ← ACI class knowledge base (~2.4 MB, 1000+ classes)
│   ├── aci_rag_embeddings.npy ← Pre-computed semantic embeddings (~9 MB)
│   └── aci_filters.json       ← APIC query filter reference guide
│
├── download_classes.py        ← 🔄 One-time: downloads ACI class metadata from Cisco DevNet
├── build_rag_dataset.py       ← 🔄 One-time: builds the RAG knowledge base
│
└── aci_advanced_test_results.md   ← Sample: 32 real-world scenario test output (Markdown)

---

🛠️ Available MCP Tools

The server exposes 12 tools to the AI client:

Tool	Type	Description
search_aci_schema	📚 Schema	Semantic search across 1000+ ACI classes using natural language
get_class_properties	📚 Schema	All properties of an ACI class with types and descriptions (supports fuzzy case-matching)
get_class_children	📚 Schema	Child classes that can exist under a given parent class (supports fuzzy case-matching)
get_class_parents	📚 Schema	Parent classes that contain a given class (supports fuzzy case-matching)
get_class_relations	📚 Schema	Unified tool to explore logical relations (incoming, outgoing, or both) for a class
get_class_relations_to	📚 Schema	Outgoing relations that originate FROM a given class pointing TO others
get_class_relations_from	📚 Schema	Incoming relations that point TO a given class FROM others
build_aci_filter	🔧 Utility	Constructs a syntactically valid and properly escaped ACI query filter string (prevents parens errors)
get_live_object_sample	🔴 Live	Fetches one real live object from APIC to show actual field values (supports fuzzy case-matching)
get_live_class_objects	🔴 Live	Queries live APIC for all objects of a class with filters, pagination, and client-side attribute filtering
get_live_object_by_dn	🔴 Live	Fetches a specific Managed Object by its Distinguished Name with client-side attribute filtering
get_api_query_guide	📖 Guide	Reference guide for building APIC filter queries

---

⚡ Quick Start

1. Prerequisites

• Python 3.10+
• Access to a Cisco APIC (or use the free Cisco DevNet Sandbox)
• An AI client that supports MCP over SSE (Claude Desktop, Cursor, VS Code with MCP extension, etc.)

2. Install Dependencies

pip install -r requirements.txt

Or install individually:

pip install fastmcp httpx sentence-transformers numpy urllib3

3. Configure Your APIC

Edit apic_config.py:

APIC_SERVERS = [
    {
        "apicname": "myFabric",           # Name you choose (used in queries)
        "url": "https://192.168.10.10",   # Your APIC IP or FQDN
        "username": "admin",
        "password": "YourPassword"
    }
]

⚠️ Security: Never commit real credentials to a public repository. Use environment variables or a secrets manager in production deployments.

4. Start the MCP Server

python aci_mcp_server.py

Expected output:

INFO: Starting MCP server 'Cisco ACI Intelligent Explorer Agent' with transport 'sse' on http://127.0.0.1:9000/sse
INFO: Uvicorn running on http://127.0.0.1:9000

5. Connect Your AI Client

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "cisco-aci": {
      "url": "http://127.0.0.1:9000/sse"
    }
  }
}

Cursor — add to .cursor/mcp.json:

{
  "mcpServers": {
    "cisco-aci": {
      "url": "http://127.0.0.1:9000/sse"
    }
  }
}

---

🔄 Script Reference — When to Run What

The main server (aci_mcp_server.py) is the only file you run day-to-day. The other scripts are one-time setup or periodic update tools:

aci_mcp_server.py — Run Every Time You Use the System

python aci_mcp_server.py

• Starts the MCP server on http://127.0.0.1:9000/sse
• Loads the RAG dataset and semantic model on startup (~10-15 seconds)
• Restart this if you: edit apic_config.py, add new APIC servers, or update mcp_config/ files

---

download_classes.py — Run Once at Setup (or on ACI Version Upgrade)

python download_classes.py

• Downloads ACI class metadata from Cisco DevNet documentation
• Saves JSON files into aci_classes_json/ directory
• When to re-run: Only when Cisco releases a new ACI software version and you want updated class definitions

---

build_rag_dataset.py — Run After download_classes.py

python build_rag_dataset.py

• Reads all JSON files from aci_classes_json/
• Enriches data with a curated Acronyms/Synonyms Dictionary (29 entries: VRF, EPG, BD, AEP, vPC, LACP, OSPF, CDP, STP, VMM domain, L3Out EPG, Filter/ACL, Contract Subject, VLAN Pool and more)
• Dynamically extracts configurable properties (isConfigurable=True) for all classes to prevent system noise
• Builds mcp_config/aci_rag_dataset.json (the knowledge base)
• Computes vector embeddings → mcp_config/aci_rag_embeddings.npy
• When to re-run: After download_classes.py, or if you modify class data / synonym mappings

---

Full Setup Flow (First-Time or ACI Version Update)

Step 1:  python download_classes.py
         └─ Downloads class metadata from Cisco DevNet → aci_classes_json/

Step 2:  python build_rag_dataset.py
         └─ Builds knowledge base → mcp_config/aci_rag_dataset.json
         └─ Computes embeddings   → mcp_config/aci_rag_embeddings.npy

Step 3:  python aci_mcp_server.py
         └─ Server ready at http://127.0.0.1:9000/sse

💡 Tip: The mcp_config/ files are already included in this repository. For most users, you only need Step 3 (start the server directly). Steps 1 and 2 are only needed when updating for a new Cisco ACI version.

---

🔒 Security Design

Protection	Description
No credential leaks	Error messages to AI clients never contain APIC URLs, usernames, passwords, or tokens — sensitive details stay in server logs only
GET-only	The server exclusively uses HTTP GET requests — it cannot create, update, or delete any fabric object
Rate limiting	Sliding-window limiter (30 requests / 60 seconds) prevents AI loops from flooding your APIC
Input validation	All DN inputs are validated with a strict regex — path traversal attacks and injection attempts are blocked before any network call
Page size control	Single queries return at most 1,000 objects; pagination with page parameter supports fetching large datasets safely
Client-Side Attribute Filtering	Prevents 400 Bad Request by fetching all fields internally from APIC and filtering attributes in Python (rsp_props) before returning JSON
Case-Insensitive Normalization	Prevents AI matching errors by dynamically normalising query class names (e.g. fvbd -> fvBD)
AI Error Recovery Hints	Every validation error (invalid filter, bad DN, wrong rsp_props, rate limit) includes a _retry_hint field that tells the AI exactly how to fix and retry the call

---

💬 Example Queries

Once connected, ask your AI natural language questions:

"Show me all tenants in the fabric"
"Which EPGs are providing the 'web-contract'?"
"Find all Bridge Domains without subnets in tenant CHA_PCIDSS_TN"
"What is the operational status of all ports on node-101?"
"Are there any faults with severity 'critical' or 'major'?"
"Show BGP peer configuration for node-101 and compare to runtime state"
"Which LLDP policies have TX disabled and where are they applied?"
"Find EPGs with static port bindings but no active endpoints"
"What are the active VTEP tunnels and which nodes do they belong to?"

---

📋 Requirements

fastmcp>=0.1.0
httpx
sentence-transformers
numpy
urllib3

Install all at once:

pip install fastmcp httpx sentence-transformers numpy urllib3

---

🧪 Test Results

See aci_advanced_test_results.md for a complete diagnostics test run output.

A total of 32 real-world operational and audit scenarios (including advanced troubleshooting, logical relation tracing, DN drill-down exploration, and example query runs) were successfully executed against the Cisco DevNet Sandbox APIC. The results file contains full details of the tool call flows, arguments, and live APIC responses, demonstrating successful end-to-end execution of the MCP server.

---

🤝 Contributing & Feedback

Contributions, issues, and feature requests are welcome! Feel free to:

• Open an Issue to report bugs or suggest new features.
• Start a Discussion (if enabled) if you have questions or ideas to share.
• Submit a Pull Request (PR) to improve the codebase.

For direct feedback, you can reach out via email: ciftcigkhn@gmail.com

---

📄 License

This project is provided for educational and operational use under the MIT License. Not affiliated with or endorsed by Cisco Systems, Inc.

---

🇹🇷 Türkçe Dokümantasyon

Türkçe kullanım kılavuzu için bkz: README_TR.md