Configuration¶

The Nautobot MCP Server is configured entirely via environment variables, either set directly in your shell or loaded from a .env file in the working directory.

Environment Variables¶

Required¶

Variable	Description	Example
`NAUTOBOT_BASE_URL`	Your Nautobot instance URL	`https://nautobot.example.com`

Nautobot Connection¶

Variable	Description	Default
`NAUTOBOT_VERIFY_SSL`	Verify SSL certificates when connecting to Nautobot	`true`
`NAUTOBOT_CA_BUNDLE`	Path to a CA bundle (PEM) to verify Nautobot's certificate against, for private/internal CAs	(none)
`NAUTOBOT_TIMEOUT`	API request timeout in seconds	`60`

MCP Server¶

Variable	Description	Default
`MCP_SERVER_NAME`	Server identifier shown in MCP client connections	`nautobot-mcp-server`
`MCP_TRANSPORT`	Transport protocol (`streamable-http` or `sse`)*	`streamable-http`
`MCP_SERVER_HOST`	Host address to bind	`0.0.0.0`
`MCP_SERVER_PORT`	Port number to bind	`8000`
`LOG_LEVEL`	Logging level (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`)	`INFO`
`LOG_FORMAT`	Log output format: `text` (human-readable) or `json` (one structured object per line)**	`text`

Reference Transport Types. *Reference Logging.

MCP Client Cache¶

Variable	Description	Default
`MCP_CLIENT_TTL`	Seconds before a cached per-user client pair is re-initialized	`3600`
`MCP_CLIENT_CACHE_SIZE`	Maximum number of per-user client pairs to cache (LRU eviction above this)	`100`
`MCP_SCHEMA_CACHE_TTL`	Seconds before the shared GraphQL schema and OpenAPI spec are refreshed in the background; the existing copy keeps being served meanwhile	`3600`
`MCP_AUTH_CACHE_TTL`	Seconds a bearer token's validation verdict (accepted or rejected) is reused before it is re-checked against Nautobot; `0` re-validates on every request	`300`

Query Safety Limits¶

Variable	Description	Default
`MAX_FIELDS`	Maximum number of fields allowed in a single GraphQL query	`100`
`MAX_DEPTH`	Maximum nesting depth allowed in GraphQL queries	`5`
`MAX_GRAPHQL_LIMIT`	Maximum objects returned per GraphQL list query; used as default when unspecified and hard cap when exceeded	`250`
`MAX_REST_LIMIT`	Maximum records returned by a single REST read	`250`
`MAX_RESPONSE_KB`	Maximum serialized size (KB) of a single tool response before it is replaced with a `response_too_large` signal	`1024`
`MAX_PAGE_LIMIT`	Maximum pages to auto-paginate in REST API requests (0 = unlimited)	`5`
`MAX_CONCURRENT_REQUESTS_PER_USER`	Maximum concurrent Nautobot API requests per user token	`5`

Reference Query Safety Limits.

Transport Types¶

The server supports two MCP transport protocols:

streamable-http (recommended): Modern bidirectional streaming, uses the /mcp endpoint.
sse: Server-Sent Events, uses the /sse endpoint. Compatible with older MCP clients.

Set via the MCP_TRANSPORT environment variable. When changing the transport type, ensure your MCP client is configured to use the corresponding endpoint path.

Query Safety Limits¶

MAX_FIELDS: Prevents overly broad queries. Queries exceeding this limit require confirmation before execution.
MAX_DEPTH: Controls how deeply nested relationships can be queried (e.g., device → interface → ip_address → namespace). Deeper queries require confirmation.
MAX_GRAPHQL_LIMIT: Hard cap on the number of objects returned per GraphQL list query. When a limit exceeding this value is requested — whether as a query variable or as an inline argument in the query string (e.g., devices(limit: 500)) — it is clamped down. When no limit is provided at all, this value is applied automatically to each top-level list field in the query. This prevents unbounded queries from overwhelming Nautobot on large instances. Note that nested list fields (e.g., the interfaces within a device) are not capped, because Nautobot does not accept a limit on them; use MAX_DEPTH and MAX_RESPONSE_KB to bound deeply nested queries.
MAX_REST_LIMIT: Hard cap on the number of records returned by a single REST read. A request for more records than this is lowered to it, and a request that specifies no number at all gets this many.
MAX_RESPONSE_KB: Caps the serialized size of any single tool response (~1 MB by default). If a result would exceed this, the tool returns a response_too_large signal with the actual and allowed sizes plus a hint to narrow the request, rather than returning a payload large enough to overflow the model's context window or be truncated mid-response. Lower it for small-context models.
MAX_PAGE_LIMIT: Caps the number of pages followed during REST API auto-pagination, preventing runaway requests on large datasets. When the cap stops pagination early, the result is explicitly flagged as incomplete.
MAX_CONCURRENT_REQUESTS_PER_USER: Limits how many Nautobot API requests a single user can make concurrently, preventing one user from saturating the server.

TLS/SSL¶

The MCP server listens on plain HTTP by default (port 8000). For production deployments requiring HTTPS, place a reverse proxy (nginx, Apache, Caddy, Traefik, etc.) in front of the server.

The MCP server itself does not need any TLS configuration - the reverse proxy should handle termination and forward plain HTTP traffic to the server on port 8000.

The settings above (inbound, client → MCP server) are separate from how the MCP server reaches Nautobot (outbound). If your Nautobot is fronted by a private or internal CA, set NAUTOBOT_CA_BUNDLE to a CA bundle (PEM) so the server can verify Nautobot's certificate — the secure alternative to disabling verification with NAUTOBOT_VERIFY_SSL=false.

Health Check¶

The server exposes an unauthenticated GET /health endpoint that returns 200 with {"status": "ok"}. It is served on the same port as the MCP endpoint (default 8000) but requires no bearer token, so load balancers, ingress controllers, and container orchestrators (Kubernetes liveness/readiness probes, Docker HEALTHCHECK) can probe it directly instead of the authenticated /mcp (or /sse) endpoint.

Authentication¶

The Nautobot MCP Server uses per-user Bearer token authentication. Each MCP client supplies their own Nautobot API token as an HTTP Bearer token when connecting. The server validates the token against Nautobot and caches the verdict for MCP_AUTH_CACHE_TTL seconds (default 300). Set the TTL to 0 to validate every request. No shared server-side token is required or stored.

This means:

Every user authenticates with their own Nautobot credentials
Invalid tokens are rejected before any tools are accessible
All Nautobot API calls are made with the connecting user's token, providing only their user access level and a per-user audit trail in Nautobot's own logs