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`

*Reference Transport Types.

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`

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_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 no limit is provided, this value is injected automatically as a query variable. 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. This prevents unbounded queries from overwhelming Nautobot on large instances.
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.
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 on each new connection - 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