Skip to main content
Glama

centralmcp — HPE Networking MCP toolkit

License Python MCP CI Docs Release

centralmcp banner showing 6,144 generated operations, 6,703 backend tools, 3 minimal router tools, and nine platform surfaces with embedded RAG

The banner tracks the current backend catalog: a large tool surface stays available on demand, while the MCP client itself only ever sees three router tools by default.

Low-token Model Context Protocol (MCP) server for HPE Networking automation: Aruba Central, HPE GreenLake Platform (GLP), ClearPass, Juniper Mist, Apstra, ArubaOS 8 migration automation, EdgeConnect, HPE Aruba UXI, and Axis Atmos Cloud.

centralmcp gives MCP-capable AI clients a low-token way to search Aruba/HPE docs, look up exact OpenAPI details, inspect Central health, run troubleshooting workflows, manage configuration, execute guarded ArubaOS 8 migrations, and use guarded GreenLake Platform operations. It is built around direct REST calls with httpx.

For the full visual walkthrough of this same information — audience picker, diagrams, and write-safety flow — see the centralmcp GitHub Pages site. This README stays intentionally short; canonical guides live under docs/.

Who it's for

You are...

Start with

A first-time MCP user

The five-minute credential-free quickstart below, then Getting started

An Aruba network operator

Example prompts and typed product workflows

A centralmcp developer

Architecture overview and Contributing guide

Related MCP server: HPE Aruba Networking Central MCP Server

Five-minute credential-free quickstart

Verify the install, build the router catalog, and start the MCP HTTP server before adding any Aruba Central or GreenLake Platform credentials:

git clone https://github.com/secure-ssid/centralmcp.git
cd centralmcp
python3 scripts/setup_wizard.py --yes --skip-credentials
uv run python scripts/doctor.py
MCP_PORT=8010 bash scripts/run_http_router.sh

Expected outcomes:

  • The wizard prints each completed phase and ends with a setup-complete summary; no Central/GLP calls are made.

  • doctor.py reports local dependency, config-path, and index checks — everything reads OK or lists what to fix, without calling any vendor API.

  • The HTTP router prints a Uvicorn running on http://127.0.0.1:8010 line and keeps running in the foreground.

The same six steps this diagram shows — clone, run the wizard, check the doctor, connect, discover, and call safely — are exactly what the commands above walk through.

Connect any MCP-capable client to http://127.0.0.1:8010/mcp, then try a credential-free discovery call:

find_tool("ask Aruba docs with citations")
invoke_read_tool("ask_docs", {"question": "WPA3 SAE transition mode", "top_k": 5})

Expected outcome: a short, cited answer from the embedded docs index — this call only reaches the local RAG index, never Central or GLP.

Write safety at a glance

  • find_tool only searches the local tool catalog; it never calls a vendor API.

  • invoke_read_tool blocks any backend tool that is not annotated read-only.

  • invoke_tool is deliberately marked destructive because it can also dispatch write/destructive backend tools — use it only when a write is intended.

  • Use dry_run=True first when supported; real execution then requires either confirm=True or MCP elicitation, depending on the tool schema.

  • Optional product writes stay blocked by default (CENTRALMCP_PRODUCT_ACCESS=read-only); a global or per-platform override is required for lab read-write access.

  • Credentials stay in config/credentials.yaml or environment variables and are never committed.

See Tool router for the complete discovery/dispatch/write-safety model.

Project snapshot

Area

Current snapshot

Tool catalog

Non-additive profiles: 363 core tools / 2824 read-only optional starters / 5804 read-write optional starters; complete backend index: 6,703

RAG

51,737 prose chunks; 244 specs, 3,796 endpoints, 11,293 schemas, 60,568 fields, 102 advisories, 346 lifecycle records

Optional platforms

ClearPass, Mist, Apstra, AOS8, EdgeConnect, UXI, Axis Atmos Cloud

Safety

Per-platform write gates, dry-run + confirmation, HTTP host/origin and bearer controls, credential-gated live-test config

Full per-backend counts live in Tool catalog. See the 0.7.0 release notes for everything added in the current release, and the capability gap matrix for reproducible tool/benchmark comparisons.

Why the router matters

Point your MCP client at one server: mcp_servers/tool_router.py. The recommended minimal profile keeps the client-visible tool list at three entries while still reaching the full backend catalog:

  1. find_tool — discover the right backend tool.

  2. invoke_read_tool — dispatch read-only calls.

  3. invoke_tool — dispatch intentional write/destructive calls only.

Task-oriented guides

Need

Guide

Full setup, credentials, and MCP client connection

Getting started

Copy/paste stdio or streamable HTTP client config

MCP client recipes

Router modes, toolsets, and safe dispatch in depth

Tool router

Real prompts with expected call shapes

Example prompts

Enable ClearPass, Mist, Apstra, AOS8, EdgeConnect, UXI, or Axis

Optional product starters

Typed product-specific workflow roadmap

Product workflows

Fix setup, credential, HTTP, or catalog issues

Troubleshooting

Architecture, data flow, and safety diagrams

System overview

Every backend's tool counts and coverage

Tool catalog

The complete task-based visual gateway

centralmcp GitHub Pages

Every documentation page, grouped by purpose

docs/README.md

Contribute, get support, or report a security issue

CONTRIBUTING.md, SUPPORT.md, SECURITY.md

Local setup essentials

The default MCP client profile stays lean:

CENTRALMCP_ROUTER_MODE=minimal
CENTRALMCP_TOOLSETS=central,glp,rag

Enable optional products only when needed:

CENTRALMCP_PRODUCTS=clearpass,mist,apstra,aos8,edgeconnect,uxi,axis,design
CENTRALMCP_PRODUCT_ACCESS=read-only

.claude/launch.json ships a matching minimal aruba-tool-router launch profile for daily use. find_tool omits full JSON schemas by default; request include_schema=true only when a client needs the full parameter shape.

Build or refresh the router tool index, and download the prebuilt RAG/OpenAPI indexes instead of scraping locally:

uv run python scripts/ingest_tools.py --products all
uv run python scripts/download_indexes.py

See Getting started for credentials, region selection, optional-product env vars, and the full ingestion/refresh path.

Streamable HTTP mode

MCP_PORT=8010 bash scripts/run_http_router.sh

Then point any MCP-capable client at http://127.0.0.1:8010/mcp. The server also exposes /livez, /readyz, and /healthz. Non-loopback binds require explicit MCP_ALLOWED_HOSTS/MCP_ALLOWED_ORIGINS and can be protected with MCP_HTTP_BEARER_TOKEN. See MCP client recipes for copy/paste stdio and HTTP configs.

Project layout

mcp_servers/     Low-token router + Central/GLP/RAG/optional-product servers
pipeline/        httpx clients, 8-stage migration pipeline, SSID helpers
ingestion/       Docs/API scraping and LanceDB + SQLite index builders
docs/            Setup, router, architecture, product, and release guides
scripts/         Setup wizard, local doctor, HTTP router helper, release validation
tests/           Unit, integration, and RAG eval coverage
config/          Credentials template; real credentials stay git-ignored
run_pipeline.py  Migration pipeline CLI
run_ssid.py      SSID helper CLI

The full repository map, including generated/git-ignored paths, lives in System overview.

Validation

uv run pytest tests/unit -q
uv run python scripts/validate_release.py --catalog-products all --strict-rag --strict-tool-index --min-tools 6703

The release helper runs unit tests, optional RAG/API eval when indexes exist, tool catalog floor checks, and local tool-index freshness checks. Unit tests also include static guards for the active MCP/pipeline code, committed low-token MCP config examples, local-only config files, router product/toolset docs, bounded generic read-only GET tools, MCP list default bounds, RAG/search top_k bounds, public tool-count claims, tool-count docstrings, tracked Markdown local links and images, Pages sitemap and robots metadata, documented router example arguments, product workflow tool-name tables, and wizard optional-product env tables.

centralmcp is an independent HPE Networking MCP toolkit, improved by watching the official MCP ecosystem and community work:

Disclaimer

centralmcp is an independent community project. It is not an official HPE or HPE Aruba Networking product and is not endorsed by or supported by HPE.

License

MIT - see the repository license. Generated API metadata and upstream implementation references are documented in THIRD_PARTY_NOTICES.md.

Available Tools

16 tools
ask_docsA
Read-onlyIdempotent

Ask Aruba/HPE docs for a compact cited answer.

Use this for prose/how-to questions when you want a short answer instead of raw retrieval hits. Exact endpoint/schema questions should still use lookup_api first.

Inputs: query (required), top_k.

evaluate_compliance_policyA
Read-onlyIdempotent

Evaluate already-retrieved observations against a declarative compliance policy.

Pure, bounded, read-only evaluation only -- this never calls invoke_tool/invoke_read_tool or any backend itself, and never fetches anything. Fetch device/config/inventory state first (e.g. one or more invoke_read_tool results), then pass the already-retrieved data here as observations alongside a declarative policy. The architecture is inspired by NAPALM's compliance_report (a fixed comparison- operator dispatch table evaluated over structured state) and by Nornir-style aggregate run counts, but is implemented independently in pipeline/compliance.py with this repository's own bounds and conventions -- no eval/exec, no arbitrary expressions, no dynamic imports, and no write/destructive tool is ever reachable from here.

Args: observations: bounded (max 100) list of objects, one per device/ entity already retrieved by the caller (e.g. a single invoke_read_tool result, or one element of a list response). Never fetched by this tool. policy: bounded (max 50) list of rule objects, each with "field" (a dotted/indexed path, e.g. "interfaces[0].status" or "firmware.version" -- Mapping key lookup and Sequence integer indexing only, never eval/attribute access), "operator" (one of "eq", "ne", "lt", "le", "gt", "ge", "contains", "in", "regex_fullmatch", "version_gte", "version_range", "exists", "not_exists"), and "expected" (required for every operator except exists/not_exists). Optional per-rule "id" (defaults to "rule_"), "severity" ("critical"/"error"/"warning"/ "info", default "error", informational only -- it does not change pass/fail logic), and "optional" (bool, default False -- a missing field on an optional rule is reported "skipped" instead of "error"). A structurally invalid policy (unknown operator, malformed field path, an "expected" shape that does not match its operator, an unparsable regex/ version value, or exceeding a bound) is rejected before any observation is evaluated. policy_id: free-text label carried through into the report and artifact only. max_result_entries: bounded per-rule result detail cap (default 200, max 500). Aggregate counts always reflect the true total even when the detail list is capped -- see "results_truncated"/"results_total".

Returns "ok", "compliant" (True only when every rule for every observation passed or was explicitly skipped -- never True while any "fail"/"error" result exists), "counts" (pass/fail/error/skipped totals), "observations" (per-observation compliant flag + counts), "results" (bounded per-rule detail), "results_total"/ "results_truncated", and "artifact" (a compliance_report-shaped payload suitable for pipeline.artifact_contracts.write_artifact -- never written to disk by this tool). A structurally invalid policy/ observations input fails closed with "ok": False and a bounded "error" message before any rule evaluation begins.

Inputs: policy (required), observations (required), policy_id, max_result_entries. Returns: object

find_clientA
Read-onlyIdempotent

Find a client by name / MAC / IP.

Inputs: query (required). Returns: object

find_deviceA
Read-onlyIdempotent

Find a device by serial number.

Inputs: query (required). Returns: object

find_toolA
Read-onlyIdempotent

Find tools by query. Combines semantic search + tool-name keyword match.

Call this first when you need an action. The returned name is what you pass to invoke_read_tool for read-only tools or invoke_tool for writes. Results are deduplicated; semantic matches are annotated match='semantic', name-overlap matches match='keyword', and safety flags mirror backend ToolAnnotations. Results are compact by default; set include_schema=True only when you need the full JSON schema for a selected tool. Optional platform, server, normalized capability, curated/generated origin, and exact OpenAPI operation-ID filters apply to both keyword and semantic matches.

Args: query: What you want to do. e.g. "create a VLAN", "disconnect a client". top_k: 1-10 results (default 5). include_schema: Include full JSON schemas in results. Defaults to False to keep MCP responses compact. platform: Filter by normalized platform, such as central, glp, mist, clearpass, or apstra. server: Filter by exact backend server name, such as aruba-monitoring. capability: Filter by read, diagnostic, write, or destructive. origin: Filter by curated or generated implementation. operation_id: Filter by an exact generated OpenAPI operationId.

Inputs: query (required), top_k, origin, server, +4 more. Returns: result

get_global_scope_idA
Read-onlyIdempotent

Return the global (org-wide) scope-id.

Inputs: no named parameters. Returns: object

invoke_read_toolA
Read-onlyIdempotent

Call a read-only Aruba tool by name (from find_tool).

This refuses tools that are not annotated read-only. Use invoke_tool only for write/destructive tools after explicit user intent.

Args: cursor: Opaque next_cursor value from a previous truncated response, to resume it from where it left off. Only ever returned by this tool for capability "read" tools -- it is process-local (invalidated by a server restart), integrity protected, time-limited, and bound to this exact tool name and these exact arguments. A malformed/tampered/expired/mismatched cursor returns an error and never reaches the backend.

Inputs: name (required), cursor, arguments.

invoke_read_tool_batchA
Read-onlyIdempotent

Dispatch a bounded, ordered batch of read-only tool calls in one round trip.

Nornir-inspired bounded fan-out: each entry in calls is dispatched sequentially (no concurrency in this version -- deterministic ordering and rate-limit safety over throughput) through the identical read-only gate/response-bounding path invoke_read_tool itself uses. One call's failure never aborts the rest: every call gets its own ordered result entry plus rolled-up aggregate counts, never a raised exception and never a success-shaped failure. A write/destructive/unknown tool named in any entry is rejected for that entry alone and never reaches the backend (same gate as invoke_read_tool).

Args: calls: bounded (max 25) ordered list of call objects, each with required "name" (exact backend tool name from find_tool), optional "arguments" (object, default {}), optional "id" (caller-supplied correlation string, max 100 chars, unique within the batch -- defaults to the call's list index as a string), and optional "cursor" (an opaque next_cursor from a previous truncated single-call or batch-item read of this exact tool+arguments, resumed exactly like invoke_read_tool's own cursor argument). "arguments" is bounded to 20,000 serialized bytes and 8 levels of nesting per call -- an oversized/malformed call entry is rejected with status "invalid_call" before any dispatch is attempted for that entry, and never included in a validation-error message (so a secret placed in "arguments" is never echoed back). Duplicate ids reject the whole batch before any dispatch: correlating results by id is the point of supplying one, and silently returning two entries with the same id would make that impossible.

Rate limiting is charged per backend call, not per batch, so a 25-call batch draws 25 tokens from the same bucket a single invoke_read_tool call draws one from.

Returns "ok" (True only when every call in the batch succeeded -- never True while any failure exists), "results" (ordered list, one entry per call, each with "index", "id", "tool", "server", "status" -- one of "ok", "error", "blocked", "unknown_tool", "invalid_cursor", "invalid_call" -- and either "result" (on "ok") or "error" (bounded to 500 characters, otherwise)), "counts" ("total"/"succeeded"/ "failed"), "failed_ids" and "failed_indexes" (both ordered, one entry per failed call), and "truncated" (True when the response had to be shrunk to fit the configured byte budget -- CENTRALMCP_ROUTER_BATCH_RESPONSE_MAX_BYTES, default 300000). Each item additionally gets its own share of that budget while dispatching, so no single call can consume the whole batch's budget. The returned response is strictly within budget.

Inputs: calls (required). Returns: object

invoke_toolA
Destructive

Call an Aruba tool by name (from find_tool). Arguments is a kwargs dict.

Example: invoke_tool("create_vlan", {"vlan_id": 200, "vlan_name": "Guest"})

Dispatches through the owning backend's FastMCP tool manager, so arguments get FastMCP validation/coercion and the router's request Context is forwarded — this is what lets the async, ctx-requiring destructive ops tools (reboot_device/port_bounce/poe_bounce/disconnect_client) reach their confirmation elicitation. (FastMCP injects ctx here and strips it from the published schema, so callers only pass name + arguments.)

Inputs: name (required), arguments.

list_devicesA
Read-onlyIdempotent

List devices (paginated).

Inputs: limit, offset. Returns: object

list_scopesB
Read-onlyIdempotent

List Central scopes (sites, groups, global) — ID + name (paginated).

Inputs: limit, offset, full_list. Returns: object

list_sitesB
Read-onlyIdempotent

List sites (paginated).

Inputs: limit, offset. Returns: object

lookup_apiA
Read-onlyIdempotent

Exact Aruba Central API lookup — endpoints, schemas, fields, enum values.

Use INSTEAD of search_docs for "what enum values does field X accept", "which endpoint configures Y and with what method", or "what fields does schema Z have". Authoritative answers from the parsed OpenAPI specs. Returns [] when the specs hold no confident answer — fall back to search_docs in that case.

Inputs: query (required), top_k.

plan_reconciliation_scheduleA
Read-onlyIdempotent

Build a bounded, read-only, plan-only recurring reconciliation schedule.

Never creates an OS timer, cron job, or GitHub Actions schedule, and never executes a tool -- this only validates a cadence and resolves a bounded set of currently enabled tools into a schedule specification. Write/destructive tools are always excluded from the executable entry list (reported in "excluded" instead, with a reason), regardless of whether the caller explicitly requested them.

Args: cadence: either a named cadence string ("hourly", "daily", "weekly") or an object such as {"kind": "interval_minutes", "interval_minutes": 30} or {"kind": "cron", "expression": "*/15 * * * *"}. Validated structurally only -- never parsed into an actual next-run time or registered as a real schedule. tools: exact tool names to resolve via the loaded catalog. Omit to fall back to the platforms/servers filters below. platforms: normalized platform filter (e.g. "central", "glp") applied to the loaded catalog when tools is omitted. servers: exact backend server name filter (e.g. "aruba-monitoring") applied to the loaded catalog when tools is omitted. max_entries: safety ceiling on schedule entries (default 50, max 100).

Returns "ok", "cadence" (validated descriptor), "entries" (read/diagnostic tools only), "excluded" (everything else, with a reason), "dry_run" (always True), and "artifact" (a router_reconciliation_plan-shaped payload suitable for pipeline.artifact_contracts.write_artifact -- never written to disk by this tool).

Inputs: cadence (required), tools, servers, platforms, +1 more. Returns: object

plan_tool_workflowA
Read-onlyIdempotent

Build a deterministic, read-only dependency/order plan across enabled backend tools.

Never executes any tool. Every resolved tool reference is checked only against the currently loaded, enabled backend catalog (the same index find_tool searches) -- an unresolved or ambiguous reference is reported explicitly, never guessed or silently dropped.

Args: steps: bounded (max 25) list of step specs. Each step is a dict: - "id": optional stable step id (str); defaults to "step_". - "tool": exact tool name to resolve via the loaded catalog (preferred -- deterministic, exact match, never guessed). - "hint": free-text action description used only when "tool" is omitted; resolved via the same bounded keyword search find_tool uses (no semantic/embedding guessing). Marked "ambiguous" when multiple close-scoring candidates exist. - "depends_on": list of step ids (or exact tool names) that must run before this step. include_candidates: include up to 5 scored candidate tools per unresolved/ambiguous step. Defaults to False to keep the plan compact.

Returns "ok", "steps" (resolved metadata per step), "order" (topological order, or None whenever any step/dependency is unresolved or the graph has a cycle), "acyclic", "cycles", "unresolved_step_ids", "unresolved_dependencies", and "artifact" (a router_dependency_plan-shaped payload suitable for pipeline.artifact_contracts.write_artifact -- never written to disk by this tool). This never calls invoke_tool/invoke_read_tool.

Inputs: steps (required), include_candidates. Returns: object

search_docsA
Read-onlyIdempotent

Search Aruba/HPE documentation (Central config, APIs, NAC, VSG).

For EXACT API questions (enum values, endpoints, schema fields) prefer lookup_api — it is lossless; this is fuzzy retrieval.

Inputs: query (required), top_k, source.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 16 tools

    Disambiguation5/5

    Each tool targets a distinct purpose: documentation retrieval (ask_docs vs search_docs vs lookup_api), entity finding (find_client, find_device), list operations (list_devices, list_scopes, list_sites), invocation (invoke_read_tool, invoke_read_tool_batch, invoke_tool), planning (plan_reconciliation_schedule, plan_tool_workflow), and compliance evaluation. No two tools overlap in function.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with underscores (e.g., ask_docs, evaluate_compliance_policy, invoke_read_tool_batch). There are no deviations like camelCase or inconsistent verb styles.

    Tool Count5/5

    With 16 tools, the set is well-scoped for an API Central server that provides documentation, discovery, invocation, planning, and compliance evaluation. The number is neither too few to be ineffective nor too many to be cumbersome.

    Completeness5/5

    The tool surface covers the full lifecycle of interacting with Aruba/HPE backends: documentation lookup, entity discovery, tool finding, read/write invocation, batch operations, policy evaluation, and task planning. No obvious gaps exist for the server's stated purpose.

    Maintenance

    ActivityNo data
    ResponsivenessSyncing

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides AI assistants with direct access to multi-vendor network devices for tasks like configuration management, health checks, and topology discovery through 35 specialized tools. It enables natural language control over platforms including Cisco, Juniper, and Nokia using SSH, NETCONF, and SNMP protocols.
      12
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Exposes 90 production-grade tools for interacting with the complete HPE Aruba Networking Central REST API surface, including network inventory, configuration, and security management. It features enterprise-ready OAuth2 handling and semantic tool filtering for optimized performance with both hosted and local LLMs.
      -