A lightweight MCP (Model Context Protocol) server that runs inside your Kubernetes cluster, crawls your Services and endpoints via the Kubernetes API, auto-detects exposed OpenAPI specs, and builds a live, queryable index of your entire microservice surface area. It normalizes each spec (derefs, merges, fixes inconsistencies), tracks versions, and exposes the whole thing as MCP tools so agents can introspect, list, and invoke endpoints directly over in-cluster networking — essentially turning your microservices into a distributed, self-describing function registry.
A Kubernetes-native MCP server that discovers internal microservices, extracts their OpenAPI specs, and exposes type-safe MCP tools for API introspection and in-cluster endpoint invocation.
星标
—
工具
—
可用率
—
Features
Automatic Discovery: Discovers services in Kubernetes namespaces
OpenAPI Parsing: Fetches and parses OpenAPI/Swagger specifications
MCP Integration: Exposes tools via Model Context Protocol
Embedded Database: Uses Apache Derby (no external DB required)
Scheduled Refresh: Configurable auto-refresh (default: every 10 minutes)
Kubernetes cluster access (kubeconfig or in-cluster)
Quick Start
Build
mvn clean package
Run
# With local kubeconfig
java -jar target/openapi-mcp-server-*.jar
# With custom config
KUBECONFIG=/path/to/config java -jar target/openapi-mcp-server-*.jar
Docker
docker build -t openapi-mcp-server .
docker run -v ~/.kube/config:/root/.kube/config:ro openapi-mcp-server
Kubernetes Deployment
The k8s/ directory contains all the manifests needed to deploy the MCP server inside a Kubernetes cluster.
Prerequisites
Kubernetes cluster (1.24+)
kubectl configured with cluster access
Container registry access (to push/pull the image)
Build and Push Image
# Build the image
docker build -t your-registry/openapi-mcp-server:latest .
# Push to your registry
docker push your-registry/openapi-mcp-server:latest
# Check pod status
kubectl get pods -n openapi-mcp
# View logs
kubectl logs -n openapi-mcp -l app.kubernetes.io/name=openapi-mcp-server
# Check service discovery is working
kubectl exec -n openapi-mcp deploy/openapi-mcp-server -- curl -s localhost:8080/health
In-Cluster DNS Resolution
When running inside the cluster, use DNS-based URL templates for reliable service discovery:
# Kubernetes internal DNS pattern
OPENAPI_URL_TEMPLATE=http://{service-name}.{namespace}.svc.cluster.local/v3/api-docs
This allows the MCP server to resolve service endpoints using Kubernetes DNS without needing external routing.
Configuration
Environment Variables
Variable
Default
Description
DERBY_DB_PATH
./data/openapi_mcp
Path to Derby database
K8S_NAMESPACE_FILTER
(all)
Filter services by namespace
OPENAPI_PATH
/v3/api-docs
Default OpenAPI spec path
OPENAPI_URL_TEMPLATE
(none)
Custom URL template for OpenAPI discovery
DISCOVERY_LABEL
(none)
Label selector for discovery
K8S_IN_CLUSTER
false
Run in-cluster mode
KUBECONFIG
~/.kube/config
Path to kubeconfig
SCHEDULER_ENABLED
true
Enable auto-refresh
SCHEDULER_INTERVAL_MS
600000
Refresh interval (10 min)
OPENAPI_MAX_CONCURRENT_REQUESTS
10
Max concurrent OpenAPI fetch requests
OPENAPI_BACKOFF_MAX_FAILURES
3
Failures before applying backoff
OPENAPI_BACKOFF_BASE_SECONDS
60
Base backoff duration (doubles each failure)
OPENAPI_BACKOFF_MAX_SECONDS
3600
Maximum backoff duration (1 hour cap)
Scaling for Large Clusters (200+ services)
For large clusters, the server includes built-in protection mechanisms:
Rate Limiting: Limits concurrent HTTP requests to OpenAPI endpoints to avoid overwhelming the network or services. Configure with OPENAPI_MAX_CONCURRENT_REQUESTS.
Exponential Backoff: Services that fail repeatedly are temporarily skipped. After OPENAPI_BACKOFF_MAX_FAILURES consecutive failures, the service enters backoff mode. The backoff duration doubles with each additional failure, starting at OPENAPI_BACKOFF_BASE_SECONDS and capped at OPENAPI_BACKOFF_MAX_SECONDS.
Example configuration for a 500-service cluster:
# k8s/configmap.yaml
data:
OPENAPI_MAX_CONCURRENT_REQUESTS: "20" # More parallelism
OPENAPI_BACKOFF_MAX_FAILURES: "5" # More tolerant
OPENAPI_BACKOFF_BASE_SECONDS: "120" # 2 min base backoff
OPENAPI_BACKOFF_MAX_SECONDS: "7200" # 2 hour max backoff
SCHEDULER_INTERVAL_MS: "300000" # Refresh every 5 min
OpenAPI URL Template
By default, the server fetches OpenAPI specs using the cluster IP and port: http://{cluster-ip}:{port}/{openapi-path}.
You can override this with a custom URL template using placeholders:
# DNS-based discovery
OPENAPI_URL_TEMPLATE=http://{service-name}.{namespace}.svc.cluster.local/v3/api-docs
# Custom domain with service name in path
OPENAPI_URL_TEMPLATE=http://{service-name}.svc.example.com/{service-name}/v3/api-docs
# External gateway
OPENAPI_URL_TEMPLATE=https://api.example.com/{namespace}/{service-name}/v3/api-docs
Kubernetes Service Annotations
Mark your services for OpenAPI discovery:
apiVersion: v1
kind: Service
metadata:
name: my-service
annotations:
openapi.mcp.io/enabled: "true" # Enable discovery
openapi.mcp.io/path: "/v3/api-docs" # Custom OpenAPI path
spec:
ports:
- port: 8080
name: http # Port named 'http' is preferred
To disable discovery:
annotations:
openapi.mcp.io/enabled: "false"
Using the MCP
The MCP server should be deployed in your Kubernetes cluster first. Then connect your local AI tools to it via port-forward or ingress.
Step 1: Deploy to Kubernetes
kubectl apply -f k8s/
Step 2: Connect to the MCP Server
Option A: In-Cluster (recommended)
If your AI agents run inside the same cluster, use the internal DNS:
# k8s/configmap.yaml
data:
DB_HOST: "postgres.openapi-mcp.svc.cluster.local"
DB_PORT: "5432"
DB_NAME: "openapi_mcp"
DB_USER: "postgres"
# Use a Secret for the password
Flyway will automatically run the migrations on startup. The schema is database-agnostic, so it works with any JDBC-compatible database.
Schema
CREATE TABLE discovered_services (
id VARCHAR(255) PRIMARY KEY,
namespace VARCHAR(255) NOT NULL,
name VARCHAR(255) NOT NULL,
cluster_ip VARCHAR(45) NOT NULL,
cluster_port INTEGER NOT NULL,
openapi_path VARCHAR(255) NOT NULL,
status VARCHAR(50) NOT NULL,
discovered_at TIMESTAMP NOT NULL,
last_checked_at TIMESTAMP
);
CREATE TABLE openapi_specifications (
id INTEGER PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
service_id VARCHAR(255) REFERENCES discovered_services(id),
title VARCHAR(500),
version VARCHAR(100),
raw_json CLOB NOT NULL,
operations_json CLOB NOT NULL,
fetched_at TIMESTAMP NOT NULL
);
Tech Stack
Component
Technology
Language
Java 21
Framework
Spring Boot 3.2
Database Access
JDBI 3
Database
Apache Derby (embedded)
K8s Client
Kubernetes Client Java 20
OpenAPI Parser
Swagger Parser 2.1
Migrations
Flyway
Testing
JUnit 5, Testcontainers, k3s
Security Considerations
This server is designed to run inside your Kubernetes cluster and provides direct access to invoke microservice endpoints. Consider the following:
Network Isolation
Deploy in a dedicated namespace with restricted network policies
The server should only be accessible from trusted sources (other in-cluster services or via authenticated ingress)
Use K8S_NAMESPACE_FILTER to limit which namespaces the server can discover
Principle of Least Privilege
# Restrict to specific namespaces
K8S_NAMESPACE_FILTER: "production,staging"
# Avoid exposing internal/system namespaces
# Never include: kube-system, kube-public, cert-manager, etc.
invoke_endpoint Risks
The invoke_endpoint tool allows AI agents to call any discovered endpoint. This is powerful but potentially dangerous:
No authentication passthrough yet: The server calls endpoints as itself (service-to-service), not as the original user
No rate limiting on invocations: An agent could theoretically spam endpoints
Full request body control: The agent constructs the request payload
Recommendations
Start with read-only namespaces: Test with namespaces that only have GET endpoints
Use NetworkPolicies: Restrict which services the MCP server can reach
Monitor usage: Log all invoke_endpoint calls for audit
Plan for auth: Future versions will support token-based access control for MCP clients
A Kubernetes-native MCP server that discovers internal microservices, extracts their OpenAPI specs, and exposes type-safe MCP tools for API introspection and in-cluster endpoint invocation.
上次检查时间：2026-10-28。 A Kubernetes-native MCP server that discovers internal microservices, extracts their OpenAPI specs, and exposes type-safe MCP tools for API introspection and in-cluster endpoint invocation.
