Skip to content

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_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_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_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.

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