FastMCP

Link-driven MCP server for Kubernetes. Draw a link in Stacktic → tools auto-generate → kubectl apply -k → AI has database/storage/messaging tools. No code, no Docker rebuild. Supports autonomous AI agents via Dark Factory.

Architecture

                FastMCP Server - MCP over Streamable HTTP (JSON-RPC 2.0). Auto-discovers register_*_tools(mcp) from mounted tool files.

                Tool Files - Python modules mounted via ConfigMap. Each link adds/removes a tool file.

                cloud.env - Connection env vars per link (MCP_POSTGRES_*, MCP_KAFKA_*, etc.). SOPS encrypted.

                Dark Factory - Autonomous AI agent loop. Runs tasks on schedule using Claude API + MCP tools.

                OIDC / API Key - Keycloak OAuth 2.0 + PKCE or APISIX API key authentication.

Component Attributes

Attribute	Example	Description
`namespace` REQ	`mcp`	Kubernetes namespace for all MCP resources
`port` REQ	`8080`	Container port for the MCP server
`transport`	`streamable-http`	MCP transport protocol
`server_name`	`stacktic-mcp`	MCP server name reported to clients
`api_key`	`my-secret-key`	API key for APISIX gateway authentication
`kubectl_access`	`Readonly`	`Disabled` (default) / `Readonly` / `ReadWrite`. Enables kubectl + OPA compliance tools.
`kubectl_all_namespaces`	`false`	When true, kubectl tools can access all namespaces
`knowledge_repo_url`	`https://github.com/org/mcp-ai-knowledge`	Git repo with curated Stacktic knowledge (knowledge_base.json). Enables knowledge MCP tools.
`knowledge_repo_branch`	`main`	Branch for knowledge repo

Dark Factory Notification Attributes (Component-Level)

These attributes are only needed if you create agent/task sub-components and want email notifications.

Attribute	Example	Description
`email_provider`	`http`	`smtp` or `http` (for Resend, Mailgun, SendGrid, etc.)
`email_from`	`ops@company.com`	Sender email address
`smtp_host` / `smtp_port`	`smtp.gmail.com` / `587`	SMTP server (when email_provider=smtp)
`smtp_user` / `smtp_password`	`user` / `pass`	SMTP credentials (when email_provider=smtp)
`email_http_api_key`	`re_xxx`	API key for HTTP email provider (Resend, Mailgun)
`email_http_url`	`https://api.resend.com/emails`	HTTP email API endpoint (default: Resend)
`notify_webhook`	`https://hooks.slack.com/...`	Default webhook URL for task notifications (Slack, Teams, PagerDuty)

Sub-Components (Dark Factory)

The Dark Factory turns FastMCP from a passive tool server into an autonomous agent platform. Create agent and ai_task sub-components to define autonomous AI agents that run on a schedule.

agent — AI Model Configuration

Each agent defines which AI model to use, API credentials, and iteration limits. Multiple tasks can share one agent. Tasks link to agents via ai_task-agent sub-component link.

Attribute	Default	Description
`ai_api_key` REQ	—	API key for the AI provider (Anthropic, OpenAI-compatible)
`ai_model`	`claude-haiku-4-5-20251001`	Model ID. Haiku recommended for cost efficiency. Sonnet for complex reasoning.
`agent_ai_provider`	`anthropic`	`anthropic` or `openai-compatible` (for vLLM, Ollama)
`ai_base_url`	—	Custom API base URL for OpenAI-compatible providers. Leave empty for Anthropic.
`ai_max_iterations`	`10`	Max tool-use loop iterations per task run. Higher = more thorough but more tokens.
`agent_enabled`	`true`	Enable/disable the agent. When `false`, all tasks linked to this agent stop. Survives pod restarts.

Sub-Component Links

Link Type	From → To	Purpose
`ai_task-agent`	ai_task → agent	Which AI runs the task. Each task can target a different agent. If missing, falls back to first available agent.
`ai_task-ai_task`	ai_task → ai_task	Task chaining. On success, triggers next task with previous output as context. Only first task needs cron.

Agent fallback: In single-agent setups, tasks without an explicit ai_task-agent link automatically use the first agent. No link needed.

ai_task — Autonomous Task Definition

Each task defines what the agent should do (natural language), when (cron), and in what mode. Link to an agent via ai_task-agent. Chain tasks via ai_task-ai_task.

Attribute	Default	Description
`task_description` REQ	—	Natural language instruction. Write it like you'd instruct a human operator.
`cron_expression`	(empty)	Cron schedule (5-field). e.g. `/30 * * *` = every 30min. Empty = run once on start.
`agent_mode`	`monitor`	`monitor` = read-only tools (safe). `act` = read + write tools (INSERT, DELETE, publish).
`retry_count`	`0`	How many retries on failure. `0` = no retry.
`retry_delay_seconds`	`60`	Seconds to wait between retries.
`notify_webhook`	—	Webhook URL for task results (Slack, Teams, PagerDuty)
`notify_email`	—	Email address for task result reports

Dark Factory — How It Works

Autonomous AI loop inside the FastMCP pod. Zero human intervention.

Step	What Happens
1. Schedule	Background asyncio loop evaluates `cron_expression` every 30s. No cron = run once on start.
2. Tool Selection	Local keyword matching selects only relevant MCP tools from task description. Zero API calls. ~90% token savings vs sending all 150+ tools.
3. Knowledge	Injects relevant Stacktic knowledge (critical attributes, attention points) into system prompt from knowledge_base.json
4. AI Loop	Calls Claude API with tools. Claude reasons → calls tools → gets results → reasons again. Repeats until done or max iterations.
5. Notify	Sends results to webhook (JSON) and/or email (styled HTML with status badge, metadata, full output)
6. History	Stores last 50 results in memory. Query via `dark_factory_status` and `dark_factory_history` MCP tools.

Enable / Disable

Method	How	Persists?
Permanent	Set `agent_enabled=false` on agent sub-component in Stacktic UI. Regenerate + apply.	Yes (encoded in ENV)
Runtime	Call `dark_factory_toggle_agent(name, false)` MCP tool from Claude Desktop or any MCP client.	No (resets on pod restart)

Dark Factory MCP Tools

Registered by dark_factory.py when agent/task sub-components exist. Interact with the autonomous loop from any MCP client.

Tool	Description
`dark_factory_status`	Get status of all agents and tasks — enabled state, last run time, last result
`dark_factory_history`	Get execution history for a specific task (default: last 10 runs)
`dark_factory_toggle_agent`	Enable or disable an agent at runtime without redeployment
`dark_factory_run_now`	Trigger immediate task execution, optionally follow the chain
`dark_factory_cost`	Per-task token usage and estimated USD cost since pod start

Links (19 Types)

Link Type	Direction	What Gets Automated
`fastmcp-database`	MCP → PostgreSQL	postgresql_tools.py — pg_query, pg_list_tables, pg_execute (write)
`fastmcp-db`	MCP → CNPG	cnpg_tools.py — cnpg_query, cnpg_list_tables, cnpg_execute (write)
`fastmcp-mongo_db`	MCP → MongoDB	mongodb_tools.py — mongo_find, mongo_aggregate, mongo_insert (write)
`fastmcp-clickhouse_db`	MCP → ClickHouse	clickhouse_tools.py — ch_query, ch_list_tables, ch_execute (write)
`fastmcp-swbucket`	MCP → SeaweedFS	s3_tools.py — s3_list_objects, s3_read_text, s3_upload_text (write)
`fastmcp-bridge`	MCP → Kafka	kafka_tools.py — kafka_list_topics, kafka_consume, kafka_produce (write)
`fastmcp-rabbitmq`	MCP → RabbitMQ	rabbitmq_tools.py — rmq_list_queues, rmq_peek_messages, rmq_publish (write)
`fastmcp-prometheus`	MCP → Prometheus	prometheus_tools.py — prom_query, prom_alerts, prom_targets (read-only)
`fastmcp-loki`	MCP → Loki	loki_tools.py — loki_query, loki_query_range, loki_labels (read-only)
`fastmcp-grafana`	MCP → Grafana	grafana_tools.py — grafana_list_dashboards, grafana_query_datasource
`fastmcp-valkey`	MCP → Valkey	valkey_tools.py — valkey_get, valkey_keys, valkey_set (write)
`fastmcp-argo_cd`	MCP → ArgoCD	argocd_tools.py — argocd_list_apps, argocd_sync (write)
`fastmcp-fastapi`	MCP → FastAPI	fastapi_tools.py — fastapi_openapi, fastapi_get, fastapi_call (write)
`fastmcp-external_source_code`	MCP → Source Code	source_code_tools.py — clone_repo, read_file, search_code
`fastmcp-stack_agent`	MCP → Stack Agent	topology.py — query_topology, list_components, run_test
`fastmcp-otel`	MCP → OTEL	Pod annotation for auto-instrumentation (no tool file)
`fastmcp-client`	MCP → Keycloak	OIDC auth (OAuth 2.0 + PKCE) via Keycloak operator client
`prometheus-fastmcp`	Prometheus → MCP	service-monitor.yaml for Prometheus scraping
`apisix-fastmcp`	APISIX → MCP	Gateway route with API key or OIDC auth

Dark Factory Tool Selection Keywords

The Dark Factory auto-selects MCP tools based on keywords in the task description. These keywords map to actual tool name prefixes. Zero API calls — local matching only.

Keyword(s)	Tool Prefix	Example Tools
prometheus, metric, alert, cpu, memory	`prom_*`	prom_query, prom_alerts, prom_targets
postgresql, postgres, sql, database	`pg_*`	pg_query, pg_list_tables, pg_execute
mongodb, mongo, collection	`mongo_*`	mongo_find, mongo_aggregate, mongo_insert
clickhouse, olap, analytics	`ch_*`	ch_query, ch_list_tables, ch_execute
kafka, topic, consumer, producer	`kafka_*`	kafka_list_topics, kafka_consume, kafka_produce
rabbitmq, rabbit, amqp, queue	`rmq_*`	rmq_list_queues, rmq_peek_messages, rmq_publish
loki, log, logs, logging	`loki_*`	loki_query, loki_query_range, loki_labels
pod, deploy, namespace, kubectl	`kubectl_*`	kubectl_get, kubectl_describe, kubectl_logs
topology, stack_agent, test, validate	(exact names)	query_topology, list_components, run_test
valkey, redis, cache	`valkey_*`	valkey_get, valkey_keys, valkey_info
s3, bucket, minio, seaweedfs	`s3_*`	s3_list_objects, s3_read_text, s3_upload_text

Generated Files

File	Condition	Contains
`k8s/deploy/base/fastmcp.yaml`	Always	Deployment + Service
`k8s/deploy/base/kustomization.yaml`	Always	Conditional configMapGenerator — tool files per link
`k8s/deploy/base/secret/cloud.env`	Always (SOPS)	MCP_* connection env vars + DARK_FACTORY_* (if agents/tasks)
`k8s/deploy/base/files/health.py`	Always	ping + server_info tools
`k8s/deploy/base/files/template_explorer.py`	Always	Stack repo clone + browse tools
`k8s/deploy/base/files/stacktic_knowledge.py`	Always	Knowledge base tools (from mcp-ai-knowledge repo)
`k8s/deploy/base/files/dark_factory.py`	__task exists	Autonomous AI loop + 6 MCP tools (status, history, toggle, run_now, cost)
`k8s/deploy/base/files/postgresql_tools.py`	fastmcp-database link	pg_* tools
`k8s/deploy/base/files/cnpg_tools.py`	fastmcp-db link	cnpg_* tools
`k8s/deploy/base/files/mongodb_tools.py`	fastmcp-mongo_db link	mongo_* tools
`k8s/deploy/base/files/clickhouse_tools.py`	fastmcp-clickhouse_db link	ch_* tools
`k8s/deploy/base/files/s3_tools.py`	fastmcp-swbucket link	s3_* tools
`k8s/deploy/base/files/kafka_tools.py`	fastmcp-bridge link	kafka_* tools
`k8s/deploy/base/files/rabbitmq_tools.py`	fastmcp-rabbitmq link	rmq_* tools
`k8s/deploy/base/files/prometheus_tools.py`	fastmcp-prometheus link	prom_* tools
`k8s/deploy/base/files/loki_tools.py`	fastmcp-loki link	loki_* tools
`k8s/deploy/base/files/topology.py`	fastmcp-stack_agent link	query_topology, list_components, run_test
`k8s/deploy/base/files/source_code_tools.py`	fastmcp-external_source_code link	clone_repo, read_file, search_code
`k8s/deploy/base/files/kubectl_tools.py`	kubectl_access != Disabled	kubectl_get, kubectl_describe, kubectl_logs + OPA compliance
`k8s/deploy/base/service-monitor.yaml`	prometheus-fastmcp link	ServiceMonitor for Prometheus scraping

Endpoints

                Internal MCP: http://{component-name}.{namespace}.svc.cluster.local/mcp

                Health Check: http://{component-name}.{namespace}.svc.cluster.local/health

                External (APISIX): https://{subdomain}.{domain}/mcp (API key or OIDC)