# mcp-server
Model Context Protocol (MCP) server for Flight Control
---
## Overview
The **MCP server** provides a read-only API layer for querying and retrieving contextual information about devices and fleets managed by [Flight Control](https://github.com/flightctl/flightctl).
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 the [flightctl-python-client](https://github.com/flightctl/flightctl-python-client) for backend communication and enforces authentication compatible with Flight Control's authorization model.
---
## Building locally
To build the container image locally using Podman, run:
```sh
podman build -t mcp-server:latest .
```
This will create a local image named `mcp-server:latest` that you can use to run the server.
---
## Pre-built Container Images
**✅ Ready-to-use images are automatically published to quay.io!**
```bash
# 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
```
### Automated Publishing
- 🔄 **Automatic builds**: Every commit merged to `main` triggers a new build
- ✅ **Quality assured**: Only builds after passing all tests (linting, type checking, unit tests)
- 🔒 **Security scanned**: All images are scanned for vulnerabilities with Trivy
- 🏗️ **Multi-platform**: Available for both `linux/amd64` and `linux/arm64`
- 🏷️ **Smart tagging**: Images tagged with `latest`, branch name, and commit SHA
> **For maintainers**: See [CONTAINER-PUBLISHING.md](./CONTAINER-PUBLISHING.md) for setup instructions and workflow details.
---
## Running with Podman or Docker
### Example: Using Automatic Configuration (Recommended)
If you've run `flightctl login`, you can mount the config directory. **Note**: The server now defaults to `streamable-http` transport for better web-based integration.
```json
{
"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"
}
}
}
}
```
### Example: Using Environment Variables
For environments where mounting the config file isn't possible:
```json
{
"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"
}
}
}
}
```
---
## Transport Configuration
The MCP server supports three transport methods with `stdio` as the default for maximum compatibility:
### STDIO (Default - Most Compatible)
- **Best for**: Local tools, command-line scripts, integrations with clients like Claude Desktop
- **Configuration**: Set `MCP_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**: Set `MCP_TRANSPORT=streamable-http`
- **Note**: Requires MCP clients that support the new streamable-http transport
### SSE (Server-Sent Events)
- **Best for**: Legacy deployments that specifically require SSE
- **Configuration**: Set `MCP_TRANSPORT=sse`
- **Default endpoint**: `http://127.0.0.1:8000/sse`
---
## Authentication Setup
The MCP server uses OIDC/OAuth2 refresh tokens for authentication. To obtain the required credentials:
1. **OIDC_TOKEN_URL**: This is typically in the format `https://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`
2. **REFRESH_TOKEN**: Obtain this from your Flight Control authentication system
- This token should have appropriate permissions to read Flight Control resources
3. **OIDC_CLIENT_ID**: Usually `flightctl` (this is the default if not specified)
---
## Configuration
The MCP server supports two configuration methods:
### 1. Automatic Configuration (Recommended)
If you've run `flightctl 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
### 2. Environment Variable Configuration
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 to `flightctl`) - **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 to `INFO`)
### 3. MCP Transport Configuration
The following environment variables control the MCP server transport and network settings:
- **MCP_TRANSPORT:** Transport mechanism (`stdio`, `sse`, `streamable-http`) - **Optional** (defaults to `stdio`)
- **MCP_HOST:** Host to bind to for HTTP transports - **Optional** (defaults to `127.0.0.1`)
- **MCP_PORT:** Port to listen on for HTTP transports - **Optional** (defaults to `8000`)
- **MCP_PATH:** Path for the MCP endpoint - **Optional** (defaults to `/mcp` for streamable-http)
- **MCP_LOG_LEVEL:** Server log level (`debug`, `info`, `warning`, `error`) - **Optional** (defaults to `info`)
### SSL Certificate Handling
The server properly handles SSL certificates in the following priority:
1. **Custom CA Certificate**: If `CA_CERT_PATH` is set, uses the specified certificate file
2. **Skip SSL Verification**: If `INSECURE_SKIP_VERIFY=true`, disables certificate verification (useful for development)
3. **System CA Bundle**: Uses the system's default certificate authority bundle (production default)
### Logging
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 via `LOG_LEVEL` environment variable
- **Structured Logging**: Includes timestamps, component names, and detailed error context
### Error Handling
The server provides robust error handling:
- **Specific Exceptions**: Uses typed exceptions (`AuthenticationError`, `APIError`, `FlightControlError`)
- **Detailed Logging**: All errors are logged with full context
---
## Running the Server
### Local Development
```bash
# 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
```
### Accessing the HTTP Endpoint
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`
### Client Connection Examples
#### For HTTP clients (streamable-http):
```python
from fastmcp import Client
# Connect to streamable-http server
client = Client("http://127.0.0.1:8000/mcp")
```
#### For Claude Desktop (stdio):
```json
{
"mcpServers": {
"flightctl": {
"command": "python",
"args": ["main.py"],
"env": {
"MCP_TRANSPORT": "stdio"
}
}
}
}
```
---
## API Endpoints
The MCP server exposes the following tool endpoints:
### Device Management
- `query_devices`: Query and filter devices using label and field selectors
- `run_command_on_device`: Execute Linux commands on specific devices
### Fleet Management
- `query_fleets`: Query and filter fleet configurations
### Events and Monitoring
- `query_events`: Query system events and audit logs
### Enrollment
- `query_enrollment_requests`: Query device enrollment requests
### Configuration Management
- `query_repositories`: Query configuration repositories
- `query_resource_syncs`: Query resource synchronization status
---
## Testing
### Live Instance Testing
To test against your actual Flight Control instance:
```bash
# Ensure you have logged in first
flightctl login
# Run the live integration test
python test_live_instance.py
```
### Unit Testing
```bash
# 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
```
### MCP Client Testing
```bash
# 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())
"
```
---
## Troubleshooting
### Common Issues
1. **Server not starting**: Check if the port is already in use
```bash
lsof -i :8000
```
2. **Authentication failures**: Verify your Flight Control credentials
```bash
flightctl login
```
3. **Connection refused**: Ensure the server is running and accessible
```bash
curl -v http://127.0.0.1:8000/mcp
```
4. **Transport issues**: Verify the transport configuration matches your client
```bash
# Check server logs
tail -f ~/.local/share/flightctl-mcp/flightctl-mcp.log
```
### Debug Mode
Enable debug logging for more detailed information:
```bash
MCP_LOG_LEVEL=debug LOG_LEVEL=DEBUG python main.py
```
---
## Migration from STDIO
If you're migrating from the previous stdio-only version:
1. **Update your client configuration** to use HTTP endpoints instead of stdio
2. **Set environment variables** for host/port configuration if needed
3. **Update firewall rules** if running on a remote server
4. **Test the connection** using the provided client examples
The server will still support stdio transport if you set `MCP_TRANSPORT=stdio`, maintaining backward compatibility.
---
## Features
- Read-only querying of **devices**, **fleets**, **events**, **enrollment requests**, **repositories**, and **resource syncs** from 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
---
## Documentation
API endpoints, filtering options, and example requests will be described in the [docs/](docs/) directory or in the OpenAPI specification.
---
## License
This project is open source. See [LICENSE](LICENSE) for details.
---
## Contributing
Issues and pull requests are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
---
