sastre-mcp
reismarcelo/sastre-mcp
An MCP server exposing Sastre tasks
Instalação
npx convez-ai reismarcelo/sastre-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
Sastre-MCP
Streamable HTTP MCP server that exposes Sastre commands (the cisco-sdwan Python package).
Requirements
- Python 3.14+
- Reachable Cisco SD-WAN Manager (vManage)
- A
config.yamlfile, useconfig.example.yamlas a template
Install
cd /path/to/sastre-mcp
python3 -m pip install -e .
Run
cp config.example.yaml config.yaml
# Edit config.yaml: sdwan_managers (name, address, credentials), mcp bearer_token, etc.
python3 -m sastre_mcp
# or: sastre-mcp
The server loads config.yaml from the current working directory.
MCP endpoint (default): http://127.0.0.1:8765/mcp (use HTTPS behind a reverse proxy in production).
Configuration file
| Section | Purpose |
|---|---|
sdwan_managers | List of SD-WAN Managers. Each entry needs a unique name plus host, port, auth (user/password or apikey), optional tenant, timeout (1–3600 s) |
default_manager | Optional; name of the manager used when a tool call omits manager. Defaults to the first entry |
mcp | HTTP bind host/port, optional bearer_token, stateless_http, cors_origins (list; empty disables CORS), disable_rate_limit (testing) |
limits | Input and DoS caps (regex length, body size, rate limit window, etc.); optional — defaults match the previous hard-coded values |
Bind rule: If mcp.host is 0.0.0.0 or ::, mcp.bearer_token is required (enforced when the file is validated).
Auth rule: For each manager, if apikey is not set (or empty), user and password are required.
Manager rule: Each sdwan_managers entry must have a unique name; if set, default_manager must match one of them.
Sensitive fields should use strong values and restrictive file permissions on config.yaml. Restrict it to the service account, e.g. chmod 600 config.yaml. Do not commit config.yaml (it is listed in .gitignore).
Environment-variable indirection for secrets
Any string value in the config may reference an environment variable, which is expanded when the file is loaded:
${VAR}— replaced with the value ofVAR; startup fails with a clear error ifVARis unset (so a missing secret never silently becomes empty).${VAR:-default}— replaced withVARif set, otherwise the literaldefault.$${— escape for a literal${when a value genuinely needs that sequence.
This works for password, apikey, bearer_token, or any other field. Example:
sdwan_managers:
- name: "primary"
address: "10.0.0.1"
user: "admin"
password: "${PRIMARY_VMANAGE_PASSWORD}"
mcp:
bearer_token: "${MCP_BEARER_TOKEN}"
Then supply the secrets from your environment or a secrets manager (systemd LoadCredential, Docker/Kubernetes secrets, Vault agent, etc.) at runtime:
export PRIMARY_VMANAGE_PASSWORD='...'
export MCP_BEARER_TOKEN='...'
python3 -m sastre_mcp
Logging
The server logs to the console and to a rotating file. The configuration is static and defined in code (sastre_mcp/__main__.py); it is not customizable via environment variables, so logging behaves identically across deployments:
| Setting | Value | Purpose |
|---|---|---|
| Root / file level | DEBUG | Root and file-handler level |
| Console level | WARNING | Console-handler level |
| Log file | logs/sastre-mcp.log | Rotating log file path (3 backups, 200 KB each) |
If the log file's directory cannot be created or the file is not writable (e.g. a --read-only container or a non-writable working directory), file logging is skipped and the server logs to the console only instead of failing to start.
Connecting MCP clients
This is a streamable HTTP MCP server, so any client that supports the HTTP transport can connect. Point the client at your MCP endpoint (default http://127.0.0.1:8765/mcp) and, when mcp.bearer_token is set in config.yaml, send an Authorization: Bearer <mcp.bearer_token> header. Start the server (python3 -m sastre_mcp) before connecting.
Replace <mcp.bearer_token> below with the token from your config.yaml. If no token is configured (local, loopback-only use), omit the Authorization header / headers block entirely.
Cursor
Add an HTTP MCP server entry to ~/.cursor/mcp.json (global) or .cursor/mcp.json in the project root:
{
"mcpServers": {
"sastre-mcp": {
"url": "http://127.0.0.1:8765/mcp",
"headers": {
"Authorization": "Bearer <mcp.bearer_token>"
}
}
}
}
Then enable the server under Cursor Settings → MCP & Integrations.
Claude Code
Add the server with the claude CLI, using the HTTP transport:
claude mcp add --transport http sastre-mcp http://127.0.0.1:8765/mcp \
--header "Authorization: Bearer <mcp.bearer_token>"
This writes the server into your Claude Code configuration. Verify it with claude mcp list, or check the connection from inside a session with /mcp. Equivalently, add it to a project-scoped .mcp.json:
{
"mcpServers": {
"sastre-mcp": {
"type": "http",
"url": "http://127.0.0.1:8765/mcp",
"headers": {
"Authorization": "Bearer <mcp.bearer_token>"
}
}
}
}
Tools
show_devices— device inventoryshow_realtime— realtime operational (commandlist, e.g.["omp","adv-routes"])show_state— bulk stateshow_statistics— statistics (optionaldays/hours)show_alarms/show_events— manager alarms and eventsshow_template_values— per-device variable values from device-template attachmentsshow_template_references— how device templates reference feature templateslist_configuration— configuration items stored on the manager (tagslist selects item groups)list_certificates— WAN edge device certificate informationlist_sdwan_managers— list configured managers and the defaultlist_show_operational_commands— catalog help for command tokenslist_configuration_tags— catalog help forlist_configurationtagsvalues
Optional output_format: text (default) or json per tool.
Selecting a manager: Every show/list tool accepts an optional manager argument naming one of the configured sdwan_managers. Omit it to use default_manager. Call list_sdwan_managers to see the available names.
Security notes
- Terminate TLS at a reverse proxy for remote access.
- Do not expose
0.0.0.0withoutmcp.bearer_token. - SD-WAN Manager credentials never appear in tool arguments; they live only in
config.yamlon the server. Tool callers can select a manager only by its configuredname.
See SECURITY.md for deployment hardening guidance and how to report vulnerabilities.
Rate limiting
A per-client-IP fixed-window limit is enabled by default (limits.rate_limit_window_secs / limits.rate_limit_max_requests; disable with mcp.disable_rate_limit).
- Behind a reverse proxy: by default the limiter keys on the direct peer address, so all clients arriving through a proxy share one bucket. Set
limits.rate_limit_trusted_proxiesto the proxy IP(s) or CIDR(s) you control; for requests from those addresses the client IP is then taken from theX-Forwarded-Forheader (the closest entry that is not itself a trusted proxy).X-Forwarded-Foris only honored when the request actually arrives from a trusted proxy, because the header is otherwise spoofable. - Multi-worker / multi-instance: counters live in process memory, so the limit is enforced independently per worker process. With
Nworkers the effective global limit is roughlyN * rate_limit_max_requestsper window. For accurate limiting across scaled deployments, enforce limits at the reverse proxy / API gateway or use a shared store (e.g. Redis). Quiet IP buckets are pruned automatically, so memory does not grow unboundedly.
vManage session pooling
Logged-in cisco-sdwan (Rest) sessions are pooled and reused per manager instead of logging in and out on every tool call. The pool is thread-safe (show tasks run in worker threads) and a given session is never used by two requests at once.
- Concurrency bound:
limits.max_sessions_per_manager(default4) caps how many sessions/connections may be open against a single SD-WAN Manager simultaneously, acting as a semaphore. When all sessions are busy, a request waits up tolimits.session_acquire_timeout_secs(default30) for one to free up; otherwise the caller gets a "busy, retry shortly" message. - Idle eviction: an idle session unused for longer than
limits.session_max_idle_secs(default600) is closed and re-created on next use, avoiding stale server-side sessions. Set to0to disable idle eviction. A reused session that fails mid-request is discarded and retried once with a fresh login. - Multi-worker / multi-instance: as with rate limiting, the pool is per process, so each worker maintains its own sessions (up to
N * max_sessions_per_managertotal acrossNworkers).
Docker
A Dockerfile builds a minimal image that runs as a non-root user.
docker build -t sastre-mcp .
# Mount config.yaml read-only and supply secrets via the environment.
# Set mcp.host to 0.0.0.0 in config.yaml so the server is reachable from outside
# the container (which requires mcp.bearer_token to be set).
docker run --rm -p 8765:8765 \
-v "$PWD/config.yaml:/app/config.yaml:ro" \
-e MCP_BEARER_TOKEN='...' \
--read-only --security-opt no-new-privileges --cap-drop ALL \
sastre-mcp
Do not bake config.yaml or secrets into the image; provide them at runtime. Terminate TLS at a reverse proxy in production.
The image's HEALTHCHECK probes SASTRE_MCP_HEALTHCHECK_PORT (default 8765). When you run the server on a non-default mcp.port, set this env var to match so the health probe targets the right port, e.g. -e SASTRE_MCP_HEALTHCHECK_PORT=9000.
For local use, the run-docker.sh helper runs the container with the current directory bind-mounted into /app (where the server looks for config.yaml):
./run-docker.sh
# Read-only mount, custom port/tag, with a bearer token from the environment:
MOUNT_RO=1 HOST_PORT=9000 IMAGE=sastre-mcp:dev MCP_BEARER_TOKEN='...' ./run-docker.sh
It forwards MCP_BEARER_TOKEN into the container only when set and applies --security-opt no-new-privileges and --cap-drop ALL. The container runs as a non-root user (uid 10001), so the mounted config.yaml must be readable by that uid.
Dev
python3 -m pip install -e ".[dev]"
pytest