
Schema-driven MCP server for Cisco ACI (APIC) — uvx niwashi-mcp. Five tools that let any LLM
Schema-driven MCP server for Cisco ACI (APIC) — uvx niwashi-mcp. Five tools that let any LLM navigate all 15,452 ACI classes by reading the fabric's own object model, with none of them hardcoded.
·
A schema-driven MCP server for Cisco ACI —
it reads the fabric's own object model instead of a fixed list of endpoints,
so any LLM can reach all 15,452 classes with no hardcoded class knowledge.
uvx niwashi-mcpThat is the whole installation. No checkout, no schema bundle, no data directory — the ACI object model travels inside the server's own dependencies.
You need Python 3.12+, uv, and an APIC to
point at. If you do not have one, the free
Cisco DevNet Always-On ACI sandbox works and
requires no hardware. Cisco publishes its hostname and credentials on that page —
read them there rather than from here, since Cisco rotates them:
export APIC_HOST=<host from the DevNet sandbox page>
export APIC_USER=<user from the DevNet sandbox page>
export APIC_PASSWORD=<password from the DevNet sandbox page>
uvx niwashi-mcpThe server listens on http://127.0.0.1:8000 — loopback only by default. Set MCP_HOST to expose it, and set MCP_API_KEYS first: it holds your APIC credentials, so a routable bind without authentication is refused.
/health answers without authentication, for load-balancer and supervisor probes.
Startup logs how many classes were indexed and which APIC release the object
model was built from.
Credentials can come from a .env file instead of the environment. The server
reads the first one that exists:
| Order | Location |
|---|---|
| 1 | $NIWASHI_MCP_ENV_FILE — an explicit path, which wins over everything below |
| 2 | ./.env in the working directory |
| 3 | .env at the root of a git checkout, when the server runs from one |
| 4 | ~/.config/niwashi-mcp/.env |
Variables already present in the environment are never overwritten by the file.
Two steps: register the server, then load the ACI skill so your agent knows how to navigate the object model.
The server speaks MCP over HTTP. Point your client at:
http://localhost:8000/mcp # local
https://your-host.example.com/mcp # behind your own TLS terminatorEdit claude_desktop_config.json:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json{
"mcpServers": {
"niwashi-mcp": {
"command": "npx",
"args": [
"-y", "mcp-remote", "http://localhost:8000/mcp",
"--header", "Authorization: Bearer <your-token>"
]
}
}
}Restart Claude Desktop. The server appears under MCP in the tool menu.
Why the
mcp-remotebridge and not"type": "http". This server speaks MCP over HTTP, butclaude_desktop_config.jsontakes a local command to launch. Given a"type": "http"entry it reports "not valid MCP server configurations and were skipped" — and it says so once, at startup, then carries on with the server silently absent.mcp-remoteis the standard bridge: a local process that speaks stdio to the client and HTTP to us. Measured against Claude Desktop on macOS, 2026-08-09.Drop the
--headerpair whenMCP_API_KEYSis unset (development only). Note the header is one argument,Authorization: Bearer <token>— splitting it, or passing only theBearer …half, produces a 401 the bridge reports as a connection failure.
claude mcp add niwashi-mcp --transport http http://localhost:8000/mcpWith authentication:
claude mcp add niwashi-mcp --transport http http://localhost:8000/mcp \
--header "Authorization: Bearer <your-token>"Add to ~/.config/opencode/opencode.json to reach the server from any project,
or to .opencode/opencode.json inside one project to scope it there:
{
"mcp": {
"niwashi-mcp": {
"type": "remote",
"url": "http://localhost:8000/mcp",
"enabled": true,
"headers": {
"Authorization": "Bearer <your-token>"
}
}
}
}Verify with opencode mcp list; the entry should read connected. OpenCode
merges the global and project files, so declaring the same server in both under
different names registers it twice and the agent sees ten tools instead of
five — which is exactly the ambiguity the five-tool surface exists to avoid.
Same URL, same bearer token, in whatever the client calls its MCP server
settings. Any client implementing MCP 2025-03-26 works: the server publishes
RFC 9728 protected-resource metadata at
/.well-known/oauth-protected-resource, so a spec-compliant client discovers
that it needs a pre-shared token rather than attempting an OAuth redirect.
A ready-made client config file lives in mcp/client/.
The object model has 15,452 classes. Without context, an LLM guesses class names — and a wrong class name returns an empty result rather than an error.
mcp/client/SKILL.md teaches an agent the object model,
how to read a schema, how DNs are built, and when to reach for each tool.
| Client | How to load it |
|---|---|
| Claude Desktop / Projects | Paste SKILL.md into the project instructions |
| Claude Code | cp mcp/client/SKILL.md .claude/niwashi-mcp.md |
| OpenCode | cp mcp/client/SKILL.md ~/.config/opencode/skills/niwashi-mcp-query/SKILL.md (or .opencode/skills/… per project). The directory name must match the skill's name: field, and it must sit beside the server declaration — tools without the skill is the failure this file exists to prevent |
| Anything else | Paste it into the system prompt or context file |
Then ask:
"List all tenants configured in this fabric."
The agent calls search_classes, get_schema and query in that order, with
no hand-written API work.
The server does not ship the ACI object model, and it does not download one. It
reads a SQLite catalogue embedded in its niwaki
dependency — a single 36 MB file covering all 15,452 managed-object classes,
built from APIC 6.0(9c). get_schema() reads that file directly; the keyword
index behind search_classes() is rebuilt from it once at startup.
That is the whole of 2.0. The five tools, their signatures and their output are unchanged; only the source of the data moved.
| 1.2.2 | 2.0 | |
|---|---|---|
| Install | git clone, download a schema bundle, extract it | uvx niwashi-mcp |
| Download | 98.8 MB tarball | the niwaki wheel (18.8 MB at 1.8.0) |
| Object model on disk | 1.82 GB across 15,452 jsonmeta files | one 36 MB SQLite file |
| Data directory to manage | data/ | none |
The APIC release is now pinned by the niwaki dependency rather than chosen by
whoever ran the collector, which is why the server logs it at startup.
If your fabric runs a different release, most of it still works — the object
model is stable across trains. What does not is narrow but quiet: classes added,
removed or renamed in your release come back empty rather than erroring, which
looks exactly like "there are none". SUPPORTED-APIC.md
explains the symptom, and is where you request a release in one line.
Both numbers below are correct, and they mean different things:
| Number | Meaning |
|---|---|
| 15,452 | Classes that exist. query() and count() accept every one of them. |
| 15,239 | Classes that are searchable. search_classes() reaches these. |
The 213-class difference is classes carrying no label, no comment and no usable property label — there is nothing to index on. They remain fully queryable once you know their name.
Class lookup is case-sensitive, structurally: the catalogue uses SQLite's BINARY
collation, so fvBd does not resolve to fvBD.
| Tool | What it does |
|---|---|
search_classes(keyword) | Weighted keyword search across the 15,239 indexed classes |
get_schema(class_name, ...) | Identifiers, DN formats, containment, children, relations, and on demand per-property constraints |
query(class_name, ...) | A scoped, filtered query against the APIC, returning a paging envelope |
get_by_dn(dn, ...) | Fetches one object directly by DN — the known-DN shortcut |
count(class_name, ...) | Tallies objects of a class without transferring them |
Discovery follows a fixed order — search_classes → get_schema → query —
because the APIC does not reject an unknown class name or a misspelled
attribute; it returns nothing at all. Two shortcuts skip it: get_by_dn when
the DN is already known, and count when the question is only "how many".
get_schema() returns className, classPkg, containedBy, contains,
dnFormats, identifiedBy, isAbstract, isConfigurable, label,
properties, relationFrom, relationTo and rnFormat, plus
property_details when you ask for it. Property details are opt-in because many
classes carry over a hundred properties; properties_filter=[...] asks for only
the ones you intend to set or filter on.
Search quality on the 74-query golden set: Recall@1 78.4 %, Recall@5 94.6 %,
MRR 0.846. Those figures are asserted as equalities in mcp/tests/baseline/,
not as floors — any movement is treated as a bug rather than a trade-off.
Per-tool reference with worked examples: docs/tools/.
| Variable | Required | Default | Description |
|---|---|---|---|
APIC_HOST | ✓ | — | APIC hostname or URL (a https:// prefix is stripped) |
APIC_USER | admin | APIC username | |
APIC_PASSWORD | ✓ | — | APIC password |
APIC_VERIFY_SSL | false | Set true to enforce TLS certificate verification | |
MCP_PORT | 8000 | HTTP port the server listens on | |
MCP_API_KEYS | — | Comma-separated bearer tokens. Unset means no authentication (development only) | |
MCP_HOST | 127.0.0.1 | Interface to bind. Loopback by default; a routable value requires MCP_API_KEYS | |
MCP_ALLOW_NO_AUTH | false | true accepts a routable bind with MCP_API_KEYS unset. Refused otherwise | |
NIWASHI_MCP_ENV_FILE | — | Explicit path to the .env file to load |
Hot reload: send SIGHUP to the process to reload MCP_API_KEYS from the
.env file without restarting — key rotation with no downtime.
Full reference: docs/configuration/settings.md.
Authorization: Bearer or X-API-Key, compared
with hmac.compare_digest so token values leak nothing through timing429WWW-Authenticate header on 401 that
points at it/health for liveness
probes, and /.well-known/* plus /register so spec-compliant clients can
complete discovery before they hold a tokenMCP_HOST without MCP_API_KEYS is
refused at startup, not merely warned aboutSIGHUPVulnerability disclosure policy: SECURITY.md.
Upgrading is mostly deletion. The tools an agent calls did not change, so a client config only needs its URL to keep working.
| What changed | What to do |
|---|---|
Distribution is niwashi-mcp, import package niwashi_mcp | Install with uvx niwashi-mcp |
python main.py is deprecated | Use niwashi-mcp, or python -m niwashi_mcp.main. The shim still works and goes away in 3.0 |
data/ and the schema download are gone | Delete the directory; drop any /data volume mount from your compose file |
query() and count() now accept 15,452 classes instead of 15,239 | Nothing — strictly more classes are valid than before |
mo:MoClassId, mo:PropId, mo:StatsClassId and mo:StatsPropId properties no longer carry an options list | Nothing. One of them listed 17,653 entries — the entire class list — into the agent's context |
SchemaLoadError can no longer be raised | A missing or unreadable catalogue raises DescriptionsLoadError instead |
Everything else holds: the same five tools, the same search scoring, the same
APIC client with its cookie authentication, retry and pagination, and
relationTo[*].cardinality still empty on every entry — the real cardinality
lives on the relation class itself.
Full detail, including what was measured to prove the swap changed nothing: CHANGELOG.md.
Only needed to develop the server or run its test suite:
git clone https://github.com/k3l0-dev/niwashi-mcp.git
cd niwashi-mcp/mcp
uv sync
uv run niwashi-mcp # reads ../.env
uv run pytestFull documentation is in docs/:
| Section | Contents |
|---|---|
docs/getting-started/ | Quickstart |
docs/concepts/ | The ACI object model, for readers who are not network engineers |
docs/tools/ | Tool reference with examples |
docs/configuration/ | Every environment variable |
docs/architecture/ | Components, startup sequence, data flow |
docs/internals/ | Catalogue adapter, search algorithm, middleware, APIC client |
Contributions are welcome. See CONTRIBUTING.md to get started.
PolyForm Noncommercial 1.0.0 — © 2026 Khalid El-Ouiali, MONARK AIOPS srl.
Free for personal, research, and noncommercial use. A commercial license is required for any commercial deployment or integration.
Contact: [email protected]
Cisco, Cisco ACI and APIC are trademarks of Cisco Systems, Inc. niwashi-mcp is an independent project, not affiliated with or endorsed by Cisco Systems, Inc.
Pick your client and paste the snippet. Each one is the same server, written the way that client expects it.
claude mcp add niwashi-mcp -- npx -y mcp-remote http://localhost:8000/mcp --header "Authorization: Bearer <your-token>"{
"mcpServers": {
"niwashi-mcp": {
"args": [
"-y",
"mcp-remote",
"http://localhost:8000/mcp",
"--header",
"Authorization: Bearer <your-token>"
],
"command": "npx"
}
}
}code --add-mcp '{"name":"niwashi-mcp","args":["-y","mcp-remote","http://localhost:8000/mcp","--header","Authorization: Bearer <your-token>"],"command":"npx"}'[mcp_servers.niwashi-mcp]
command = "npx"
args = ["-y", "mcp-remote", "http://localhost:8000/mcp", "--header", "Authorization: Bearer <your-token>"]Runs locally on your device. Your client starts the server itself, so nothing has to be hosted.
Paste this prompt into your agent. It reads this page and does the setup for you.
Read https://aiagentslisting.com/mcp/niwashi-mcp to learn what the "Niwashi Mcp" MCP server does and how to install it. Add it to my coding agent's MCP configuration as documented on that page, then confirm the server connects and list the tools it exposes.Agents can also browse this directory over MCP at https://aiagentslisting.com/api/mcp
uvx niwashi-mcpclaude mcp add niwashi-mcp --transport http http://localhost:8000/mcpThis server runs locally, so we can't read its tool list over the web yet.
We could not run this server: it ships no npx package for our sandbox and no public endpoint. The four checks that need a live server are left out, and the grade tops out at B until one exists.
Maintain this server? Claiming proves you own the listing and earns the last 4 points.
Claim this listingPaste this line near the top of your repository's README. The badge always renders the current score.
[](https://aiagentslisting.com/mcp/niwashi-mcp)Nothing comparable is listed yet.
v2.1.1niwashi-mcp v2.1.1Release notesv2.1.0niwashi-mcp v2.1.0Release notesv2.0.0niwashi-mcp v2.0.0Release notesv1.2.2Release notesv1.2.1Release notesv0.2.0Release notesv1.2.0Release notesv1.1.0Release notesv1.0.0v1.0.0 — Initial public releaseRelease notesv0.3.0Release notesv0.1.0Release notesConnect to the AI Agents Listing MCP server at https://aiagentslisting.com/api/mcp using the HTTP transport and complete the sign-in when it asks. Then call the submit_review tool for the listing "niwashi-mcp" with a rating from 1 to 5 and a short note on what worked and what did not.No reviews yet
Be the first to share your experience with this tool.
One email a week. New agents, MCP servers and skills, and what is actually getting traction.