Flight Control MCP

A read-only API for querying and retrieving contextual information about devices and fleets using the Flight Control MCP server.

Model Context Protocol (MCP) server for Flight Control

TheMCP serverprovides a read-only API layer for querying and retrieving contextual information about devices and fleets managed byFlight Control. It is designed for safe external integration, reporting, and automation, exposing a REST API that supports filtering and selector-based queries. The MCP server leverages theflightctl-python-clientfor backend communication and enforces authentication compatible with Flight Control's authorization model.

# Pull the latest stable image docker pull quay.io/flightctl/flightctl-mcp:latest # Run immediately with streamable-http transport docker run -p 8000:8000 quay.io/flightctl/flightctl-mcp:latest

For maintainers: SeeCONTAINER-PUBLISHING.mdfor setup instructions and workflow details.

{ "mcpServers": { "mcp-server": { "command": "podman", "args": [ "run", "-i", "--rm", "-p", "8000:8000", "-v", "~/.config/flightctl:/root/.config/flightctl:ro", "-e", "MCP_TRANSPORT", "-e", "MCP_HOST", "-e", "MCP_PORT", "quay.io/flightctl/flightctl-mcp:latest" ], "env": { "MCP_TRANSPORT": "streamable-http", "MCP_HOST": "0.0.0.0", "MCP_PORT": "8000" } } } }

For environments where mounting the config file isn't possible:

{ "mcpServers": { "mcp-server": { "command": "podman", "args": [ "run", "-i", "--rm", "-p", "8000:8000", "-e", "API_BASE_URL", "-e", "OIDC_TOKEN_URL", "-e", "OIDC_CLIENT_ID", "-e", "REFRESH_TOKEN", "-e", "INSECURE_SKIP_VERIFY", "-e", "LOG_LEVEL", "-e", "MCP_TRANSPORT", "-e", "MCP_HOST", "-e", "MCP_PORT", "quay.io/flightctl/flightctl-mcp:latest" ], "env": { "API_BASE_URL": "https://api.flightctl.example.com", "OIDC_TOKEN_URL": "https://auth.flightctl.example.com/realms/flightctl/protocol/openid-connect/token", "OIDC_CLIENT_ID": "flightctl", "REFRESH_TOKEN": "REDACTED", "INSECURE_SKIP_VERIFY": "false", "LOG_LEVEL": "INFO", "MCP_TRANSPORT": "streamable-http", "MCP_HOST": "0.0.0.0", "MCP_PORT": "8000" } } } }

The MCP server supports three transport methods withstdioas the default for maximum compatibility:

- Best for: Local tools, command-line scripts, integrations with clients like Claude Desktop
- Configuration: SetMCP_TRANSPORT=stdio(default)
- Why default: Maximum compatibility with existing MCP clients

Streamable HTTP (Recommended for Web Deployments)

- Best for: Web-based deployments, microservices, exposing MCP over a network
- Default endpoint:http://127.0.0.1:8000/mcp
- Configuration: SetMCP_TRANSPORT=streamable-http
- Note: Requires MCP clients that support the new streamable-http transport

- Best for: Legacy deployments that specifically require SSE
- Configuration: SetMCP_TRANSPORT=sse
- Default endpoint:http://127.0.0.1:8000/sse

The MCP server uses OIDC/OAuth2 refresh tokens for authentication. To obtain the required credentials:
-

OIDC_TOKEN_URL: This is typically in the formathttps://your-auth-server/realms/your-realm/protocol/openid-connect/token

- If you only have the base realm URL (e.g.,https://auth.example.com/realms/flightctl), the server will automatically append/protocol/openid-connect/token

REFRESH_TOKEN: Obtain this from your Flight Control authentication system

- This token should have appropriate permissions to read Flight Control resources

OIDC_CLIENT_ID: Usuallyflightctl(this is the default if not specified)

The MCP server supports two configuration methods:

1. Automatic Configuration (Recommended)

If you've runflightctl login, the server will automatically read configuration from~/.config/flightctl/client.yaml. This includes:

- API server URL
- OIDC authentication settings
- SSL certificate configuration
- Refresh tokens

The following environment variables can override or supplement the automatic configuration:

- API_BASE_URL:Base URL for the Flight Control API (e.g.,https://api.flightctl.example.com) -Optional(read from config file)
- OIDC_TOKEN_URL:Full URL to the OIDC token endpoint (e.g.,https://auth.flightctl.example.com/realms/flightctl/protocol/openid-connect/token) -Optional(read from config file)
- OIDC_CLIENT_ID:OIDC client identifier (defaults toflightctl) -Optional
- REFRESH_TOKEN:OAuth2 refresh token for authentication -Optional(read from config file)
- INSECURE_SKIP_VERIFY:Skip SSL certificate verification (true/false) -Optional(read from config file)
- CA_CERT_PATH:Path to custom CA certificate file for SSL verification -Optional
- LOG_LEVEL:Logging level (DEBUG,INFO,WARNING,ERROR) -Optional(defaults toINFO)

The following environment variables control the MCP server transport and network settings:

- MCP_TRANSPORT:Transport mechanism (stdio,sse,streamable-http) -Optional(defaults tostdio)
- MCP_HOST:Host to bind to for HTTP transports -Optional(defaults to127.0.0.1)
- MCP_PORT:Port to listen on for HTTP transports -Optional(defaults to8000)
- MCP_PATH:Path for the MCP endpoint -Optional(defaults to/mcpfor streamable-http)
- MCP_LOG_LEVEL:Server log level (debug,info,warning,error) -Optional(defaults toinfo)

The server properly handles SSL certificates in the following priority:
- Custom CA Certificate: IfCA_CERT_PATHis set, uses the specified certificate file
- Skip SSL Verification: IfINSECURE_SKIP_VERIFY=true, disables certificate verification (useful for development)
- System CA Bundle: Uses the system's default certificate authority bundle (production default)

The server uses file-based logging to avoid conflicts with the MCP protocol on stdio:

- Log Location:~/.local/share/flightctl-mcp/flightctl-mcp.log
- Log Rotation: Automatic rotation at 10MB with 5 backup files
- Log Levels: Configurable viaLOG_LEVELenvironment variable
- Structured Logging: Includes timestamps, component names, and detailed error context

The server provides robust error handling:

- Specific Exceptions: Uses typed exceptions (AuthenticationError,APIError,FlightControlError)
- Detailed Logging: All errors are logged with full context

# Run with default stdio transport python main.py # Run with streamable-http transport (for web deployments) MCP_TRANSPORT=streamable-http python main.py # Run with custom HTTP configuration MCP_TRANSPORT=streamable-http MCP_HOST=0.0.0.0 MCP_PORT=8080 python main.py

When running with HTTP transport, the MCP endpoint will be available at:

- Streamable HTTP:http://127.0.0.1:8000/mcp(default)
- SSE:http://127.0.0.1:8000/sse

from fastmcp import Client # Connect to streamable-http server client = Client("http://127.0.0.1:8000/mcp")

{ "mcpServers": { "flightctl": { "command": "python", "args": ["main.py"], "env": { "MCP_TRANSPORT": "stdio" } } } }

The MCP server exposes the following tool endpoints:

- query_devices: Query and filter devices using label and field selectors
- run_command_on_device: Execute Linux commands on specific devices

- query_fleets: Query and filter fleet configurations

- query_events: Query system events and audit logs

- query_enrollment_requests: Query device enrollment requests

- query_repositories: Query configuration repositories
- query_resource_syncs: Query resource synchronization status

To test against your actual Flight Control instance:

# Ensure you have logged in first flightctl login # Run the live integration test python test_live_instance.py

# Run unit tests python -m pytest test_flightctl_mcp.py -v # Run with coverage python -m pytest test_flightctl_mcp.py --cov=resource_queries --cov=main --cov=cli --cov-report=html

# Test the MCP server with a simple client python -c " from fastmcp import Client import asyncio async def test(): client = Client('http://127.0.0.1:8000/mcp') async with client: tools = await client.list_tools() print(f'Available tools: {[t.name for t in tools]}') asyncio.run(test()) "

-

Server not starting: Check if the port is already in use

Authentication failures: Verify your Flight Control credentials

Connection refused: Ensure the server is running and accessible

Transport issues: Verify the transport configuration matches your client

# Check server logs tail -f ~/.local/share/flightctl-mcp/flightctl-mcp.log

Enable debug logging for more detailed information:

MCP_LOG_LEVEL=debug LOG_LEVEL=DEBUG python main.py

If you're migrating from the previous stdio-only version:
- Update your client configurationto use HTTP endpoints instead of stdio
- Set environment variablesfor host/port configuration if needed
- Update firewall rulesif running on a remote server
- Test the connectionusing the provided client examples

The server will still support stdio transport if you setMCP_TRANSPORT=stdio, maintaining backward compatibility.

- Read-only querying ofdevices,fleets,events,enrollment requests,repositories, andresource syncsfrom Flight Control
- Support for filtering by labels and fields using Kubernetes-style selectors
- Context-rich JSON responses including metadata and links to related resources
- Secure OIDC/OAuth2 refresh token–based authentication
- Remote device console access for executing commands on managed devices
- Automatic pagination handling for large result sets

API endpoints, filtering options, and example requests will be described in thedocs/directory or in the OpenAPI specification.

This project is open source. SeeLICENSEfor details.

Issues and pull requests are welcome! Please seeCONTRIBUTING.mdfor guidelines.

Execute AWS CLI commands through the Model Context Protocol (MCP). Requires AWS credentials configured on the host.