AXMP OpenAPI FastMCP Server

Multiple OpenAPI backends to a single MCP server — Profile-based configuration with multi-provider OAuth support.

AXMP OpenAPI FastMCP Server는 여러 OpenAPI 호환 백엔드 서비스를 하나의 통합 MCP(Model Context Protocol) 서버로 노출하는 래퍼입니다. FastMCP 프레임워크를 기반으로 OpenAPI 스펙의 각 operation을 MCP Tool로 자동 변환하며, Keycloak/Google/GitHub/Azure OAuth 인증을 지원합니다.

---

Table of Contents

• Architecture
• Features
• Project Structure
• Installation
• Configuration
  • Environment Variables
  • MCP Profile
  • Backend Auth Config
• Usage
  • CLI Mode (HTTP)
  • CLI Mode (stdio)
  • Container Mode
  • Health Check
  • MCP Host Configuration
• Authentication
• Tool Configuration
• Docker
• Development
• CI/CD

---

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        MCP Host                                 │
│              (Claude Desktop, Cursor, etc.)                     │
└──────────────────────┬──────────────────────────────────────────┘
                       │  MCP Protocol (stdio / HTTP)
                       ▼
┌─────────────────────────────────────────────────────────────────┐
│               AXMP OpenAPI FastMCP Server                       │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  OAuth Provider (Keycloak / Google / GitHub / Azure)      │  │
│  └───────────────────────────────────────────────────────────┘  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐            │
│  │  OpenAPI     │  │  OpenAPI     │  │  OpenAPI     │  ...      │
│  │  Provider A  │  │  Provider B  │  │  Provider C  │           │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘            │
│         │                │                │                     │
│  ┌──────┴──────┐  ┌──────┴──────┐  ┌──────┴──────┐            │
│  │ httpx2 Clnt │  │ httpx2 Clnt │  │ httpx2 Clnt │             │
│  │ (API Key)   │  │ (Bearer)    │  │ (Basic)     │             │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘            │
└─────────┼────────────────┼────────────────┼─────────────────────┘
          ▼                ▼                ▼
   ┌──────────┐     ┌──────────┐     ┌──────────┐
   │ Backend  │     │ Backend  │     │ Backend  │
   │ Server A │     │ Server B │     │ Server C │
   └──────────┘     └──────────┘     └──────────┘

---

Features

• Multi-Backend 통합 — 여러 OpenAPI 백엔드를 하나의 MCP 서버로 통합
• Profile 기반 설정 — JSON 프로필로 백엔드 구성을 관리
• Multi-Provider OAuth — Keycloak, Google, GitHub, Azure 지원
• Token Forwarding — 업스트림 OAuth 토큰을 백엔드에 자동 전달
• 유연한 인증 — None / Basic / BearerToken / ApiKey 백엔드별 개별 인증
• Tool Filtering — api_maps (명시적) / route_maps (패턴) 기반 Tool 선택
• Custom Tool Naming — 기본 operationId 대신 사용자 정의 Tool 이름 지정
• Tool Description Override — Tool 설명을 프로필에서 직접 재정의
• Tool Output 전처리 — Tool별 응답 필드 include/exclude 및 필드 변환(HTML → Markdown)
• Dual Transport — stdio (로컬) / http (원격) 전송 모드
• Dual Entry Point — CLI (인자 기반) / Container (환경변수 기반)
• Multi-Arch Docker — linux/amd64, linux/arm64 지원

---

Project Structure

axmp-openapi-fastmcp-server/
├── src/axmp_openapi_fastmcp_server/
│   ├── __init__.py                      # Logging configuration
│   ├── __main__.py                      # python -m entry point
│   ├── settings.py                      # Pydantic Settings (MCP + OAuth)
│   ├── types.py                         # Enums (TransportType, OAuthProvider, AuthHeaderKey)
│   ├── multi_openapi_spec.py            # Multi-backend configuration models
│   ├── openapi_fastmcp_server.py        # Core wrapper (FastMCP + OpenAPI providers)
│   ├── runner/
│   │   ├── cli.py                       # CLI entry point (Click)
│   │   └── container.py                 # Container entry point (env-based)
│   └── auth/providers/
│       └── keycloak.py                  # Keycloak OAuth provider
├── mcp_profiles/                        # MCP profile & OpenAPI spec files
│   ├── mcp_profile_<id>.json            # Backend configuration profiles
│   └── backend_server_<id>.json         # OpenAPI spec files
├── .env                                 # Environment variables
├── Dockerfile                           # Container image definition
├── pyproject.toml                       # Project metadata & dependencies
├── .github/workflows/
│   └── cicd-for-tag.yml                 # CI/CD pipeline (Docker build & push)
└── .pre-commit-config.yaml              # Pre-commit hooks (ruff)

---

Installation

Requirements

• Python >= 3.12
• uv (recommended package manager)

Install from source

# Clone repository
git clone <repository-url>
cd axmp-openapi-fastmcp-server

# Install dependencies
uv sync

# Or with pip
pip install -e .

Install from package

pip install axmp-openapi-fastmcp-server

---

Configuration

Environment Variables

.env 파일 또는 시스템 환경변수로 설정합니다.

MCP Server Settings (AXMP_MCP_ prefix)

Variable	Description	Default	Required
AXMP_MCP_SERVER_NAME	MCP 서버 이름	-	Yes
AXMP_MCP_PORT	HTTP 리스닝 포트	21000	No
AXMP_MCP_TRANSPORT_TYPE	전송 방식 (http / stdio)	http	No
AXMP_MCP_PROFILE_BASE_PATH	MCP 프로필 디렉토리 경로	-	Yes
AXMP_MCP_PROFILE_ID	사용할 프로필 ID	-	Yes
AXMP_MCP_USE_AUTHORIZATION	OAuth 인증 활성화	False	No
AXMP_MCP_FORWARD_TOKEN_TO_BACKEND	업스트림 토큰을 백엔드에 전달	False	No
AXMP_MCP_PATH_PREFIX	AI Gateway subpath 노출용 path 한 단계 (예: weather). 설정 시 MCP와 OAuth 엔드포인트가 /weather/mcp, /weather/authorize 등 path 아래에서 서빙되고, well-known 메타데이터는 /.well-known/oauth-authorization-server/weather처럼 path가 뒤에 붙는다. /healthz는 루트 유지. 게이트웨이가 prefix를 떼지 않고 그대로 전달한다는 전제. 소문자·숫자·하이픈만 허용, 미설정 시 루트	-	No
AXMP_MCP_REDIS_URL	Redis 접속 URL. 설정 시 OAuth 스토리지가 Redis로 전환됨 (미설정 시 디스크). 형식: redis://[user[:password]@]host[:port][/db] 또는 TLS는 rediss://...	-	No
AXMP_MCP_REDIS_KEY_PREFIX	Redis 키 격리 prefix	axmp-mcp:{SERVER_NAME}	No
AXMP_MCP_REDIS_CLIENT_TTL_DAYS	DCR 클라이언트 등록 sliding TTL (일). 미사용 클라이언트 자동 청소 기간	14	No
AXMP_MCP_LOG_LEVEL	로그 레벨. DEBUG는 API 키와 자격 증명 헤더 값을 평문으로 출력하므로 로컬 디버깅에만 쓴다	INFO	No

Redis 모드는 AXMP_MCP_REDIS_URL 존재 여부만으로 활성화됩니다. 서버 시작 시 ping으로 연결을 검증하며, 실패 시 서버가 시작되지 않습니다 (silent fallback 없음). URL에 password가 포함될 수 있어 내부적으로 SecretStr로 다루며, 로그에는 host:port만 노출됩니다.

OAuth Settings (AXMP_OAUTH_ prefix)

Variable	Description	Default	Required
AXMP_OAUTH_PROVIDER	OAuth 제공자 (keycloak / okta / google / github / azure)	keycloak	No
AXMP_OAUTH_ISSUER_URL	OAuth Issuer URL (Keycloak realm URL 등)	-	Yes*
AXMP_OAUTH_CLIENT_ID	OAuth Client ID	-	Yes*
AXMP_OAUTH_CLIENT_SECRET	OAuth Client Secret	-	Yes*
AXMP_OAUTH_BASE_URL	MCP 서버 base URL (callback용). AXMP_MCP_PATH_PREFIX가 있어도 path 없이 https://<host>로 주며, 서버가 prefix를 붙여 공개 URL을 만든다	-	Yes*
AXMP_OAUTH_REQUIRED_SCOPES	필요 OAuth 스코프 (JSON 배열 문자열, 예: '["openid","profile","email","offline_access"]'). offline_access 는 업스트림 IdP 에서 refresh_token 을 받기 위해 필요. Google 은 refresh_token 을 access_type=offline 으로 받고 토큰에 offline_access 가 없어 keycloak/okta 에만 기본으로 넣음	keycloak/okta: ["openid","profile","email","offline_access"], 그 외: ["openid","profile","email"]	No
AXMP_OAUTH_STORAGE_PATH	토큰 저장 경로	~/.fastmcp/server/oauth-proxy	No
AXMP_OAUTH_FALLBACK_REFRESH_TOKEN_EXPIRY_SECONDS	upstream이 refresh_expires_in을 주지 않거나 0으로 줄 때(Okta, Keycloak offline 토큰) 자체 발급 refresh 토큰 수명(초). upstream이 값을 주면 그 값을 따름	43200 (12시간)	No
AXMP_OAUTH_FALLBACK_ACCESS_TOKEN_EXPIRY_SECONDS	upstream이 expires_in을 주지 않을 때 자체 발급 access 토큰 수명(초). Okta/Keycloak은 항상 expires_in을 주므로 보통 발동하지 않음. keycloak/okta provider에만 적용 (FastMCP 내장 Google/GitHub/Azure는 미지원)	3600 (1시간)	No
AXMP_OAUTH_TOKEN_EXPIRY_THRESHOLD_SECONDS	upstream 토큰 만료 N초 전에 선제 refresh. 0이면 만료 후 검증 실패 시에만 refresh	30	No

* AXMP_MCP_USE_AUTHORIZATION=True인 경우 필수

토큰 수명 설정은 FastMCP OAuthProxy가 클라이언트에 발급하는 자체 JWT와 저장소 TTL에만 적용됩니다. 실제 갱신 가능 여부는 upstream IdP 정책이 결정하며, Okta 정책이 설정값보다 짧으면 refresh가 invalid_grant로 실패해 재인증으로 떨어집니다. Keycloak은 보통 refresh_expires_in을 응답에 포함해 refresh fallback이 적용되지 않지만, offline_access 스코프로 받은 offline 토큰은 refresh_expires_in: 0으로 내려오며 FastMCP가 이를 미제공으로 취급하므로 fallback 값이 적용됩니다. AXMP_OAUTH_TOKEN_EXPIRY_THRESHOLD_SECONDS는 upstream access 토큰 수명보다 충분히 작게(예: 30~60) 설정해야 합니다. 수명 이상으로 설정하면 매 요청마다 upstream refresh가 발생합니다.

Example .env

# MCP Server
AXMP_MCP_SERVER_NAME="axmp-openapi-fastmcp-server"
AXMP_MCP_PORT=8000
AXMP_MCP_TRANSPORT_TYPE="http"
AXMP_MCP_USE_AUTHORIZATION="True"
AXMP_MCP_FORWARD_TOKEN_TO_BACKEND="True"
AXMP_MCP_PROFILE_BASE_PATH="/path/to/mcp_profiles"
AXMP_MCP_PROFILE_ID="1234567890"

# OAuth (Keycloak)
AXMP_OAUTH_PROVIDER="keycloak"
AXMP_OAUTH_ISSUER_URL="https://keycloak.example.com/auth/realms/your-realm"
AXMP_OAUTH_CLIENT_ID="studio-client"
AXMP_OAUTH_CLIENT_SECRET="your-client-secret"
AXMP_OAUTH_BASE_URL="http://127.0.0.1:8000"
AXMP_OAUTH_STORAGE_PATH="/path/to/.fastmcp/server/oauth-proxy"

# Redis OAuth storage (optional — enables shared storage across instances)
# AXMP_MCP_REDIS_URL="redis://:redis-password@redis.example.com:6379/0"

MCP Profile

MCP 프로필은 백엔드 서버 구성을 정의하는 JSON 파일입니다. 파일 이름은 mcp_profile_<profile-id>.json 형식을 따릅니다.

{
  "backends": [
    {
      "server_name": "studio-backend",
      "endpoint": "https://api.example.com",
      "base_path": "/",
      "timeout": 10,
      "tls_verify": true,
      "spec_file_path": "studio-api.json",
      "auth_config": {
        "type": "ApiKey",
        "api_key_name": "X-Access-Key",
        "api_key_value": "your-api-key"
      },
      "tool_config": {
        "api_maps": [
          {
            "path": "/api/v1/agents",
            "methods": ["get", "post"]
          },
          {
            "path": "/api/v1/agents/{agent_id}",
            "methods": [
              {
                "method": "get",
                "tool_name": "get_agent_by_id",
                "description": "Get agent details by ID"
              }
            ]
          }
        ]
      }
    }
  ]
}

Backend Configuration Fields

Field	Type	Description	Required
server_name	string	백엔드 식별 이름	Yes
endpoint	string	백엔드 서버 URL	Yes
base_path	string	spec 의 servers URL 이 가진 path. 요청 URL 은 endpoint + base_path + spec path 로 만들어진다. spec 의 path 가 이미 이 prefix 를 포함하면 붙이지 않는다	No (/)
timeout	float	요청 타임아웃 (초)	No (10)
tls_verify	bool	TLS 인증서 검증	No (true)
spec_file_path	string	OpenAPI spec JSON 파일 (프로필 디렉토리 기준 상대경로)	Yes
auth_config	object	백엔드 인증 설정	Yes
tool_config	object	Tool 필터링 및 커스터마이징 설정	Yes

Backend Auth Config

Auth Type	Fields	Description
None	-	인증 없음
Basic	username, password	HTTP Basic 인증
BearerToken	bearer_token	Bearer 토큰 인증
ApiKey	api_key_name, api_key_value	커스텀 헤더 API 키

---

Usage

CLI Mode (HTTP)

axmp-openapi-fastmcp-server \
  --port 21000 \
  --transport http \
  --server-name axmp-mixed-openapi-mcp-server \
  --profile-base-path /path/to/mcp_profiles \
  --profile-id 1234567890 \
  --backend-server-auth-configs "studio-backend:X-Access-Key=your-api-key,workspace-backend:X-Access-Key=your-api-key"

CLI Mode (stdio)

axmp-openapi-fastmcp-server \
  --transport stdio \
  --profile-base-path /path/to/mcp_profiles \
  --profile-id 1234567890 \
  --backend-server-auth-configs "studio-backend:X-Access-Key=your-api-key"

CLI Options

Option	Description	Default
--transport	전송 방식 (stdio / http / sse / streamable-http)	streamable-http
--port	HTTP 리스닝 포트	21000
--server-name	MCP 서버 이름	axmp-openapi-fastmcp-server-<profile-id>
--profile-base-path	MCP 프로필 디렉토리 경로	- (필수)
--profile-id	프로필 ID	- (필수)
--backend-server-auth-configs	런타임 인증 오버라이드	-

--backend-server-auth-configs Format

프로필의 auth 설정을 런타임에 오버라이드합니다:

<server-name>:<key-name>=<value>,<server-name>:<key-name>=<value>

• ApiKey: studio-backend:X-Access-Key=zmp-xxxxx
• BearerToken: studio-backend:bearer_token=eyJhbGci...
• Basic: studio-backend:username=admin,studio-backend:password=secret

Container Mode

환경변수 기반으로 실행됩니다. .env 파일 또는 시스템 환경변수를 설정한 후:

uv run axmp-container-fastmcp-server

Health Check

HTTP transport로 띄우면 GET /healthz가 200과 {"result": "success"}를 반환한다. OAuth를 켠 서버에서도 토큰 없이 호출할 수 있어서 Kubernetes probe나 모니터링에 쓸 수 있다. 백엔드와 Redis 상태는 확인하지 않으며, stdio transport에는 이 경로가 없다.

curl http://127.0.0.1:21000/healthz

MCP Host Configuration

Claude Desktop / Cursor

claude_desktop_config.json 또는 MCP 호스트 설정에 추가:

{
  "mcpServers": {
    "axmp-openapi-fastmcp-server": {
      "command": "python3",
      "args": [
        "-m",
        "axmp_openapi_fastmcp_server",
        "--transport", "stdio",
        "--profile-base-path", "/path/to/mcp_profiles",
        "--profile-id", "1234567890",
        "--backend-server-auth-configs",
        "studio-backend:X-Access-Key=your-api-key"
      ]
    }
  }
}

---

Authentication

OAuth Flow (HTTP transport)

AXMP_MCP_USE_AUTHORIZATION=True이고 transport가 http인 경우 OAuth 인증이 활성화됩니다.

MCP Client → MCP Server → OAuth Provider (Keycloak/Google/GitHub/Azure)
                │
                ├─ Token Introspection (검증)
                ├─ User Info Extraction (사용자 정보)
                └─ Scope Validation (스코프 확인)

Token Forwarding

AXMP_MCP_FORWARD_TOKEN_TO_BACKEND=True이고 백엔드 auth type이 BearerToken인 경우, 업스트림 OAuth 토큰이 자동으로 백엔드 요청에 주입됩니다.

Supported OAuth Providers

Provider	Class	Description
keycloak	KeyCloakProvider	Custom implementation with token introspection
google	GoogleProvider	FastMCP built-in
github	GitHubProvider	FastMCP built-in
azure	AzureProvider	FastMCP built-in

---

Tool Configuration

api_maps (Explicit)

특정 경로와 메서드를 명시적으로 MCP Tool로 등록합니다:

{
  "api_maps": [
    {
      "path": "/api/v1/agents",
      "methods": ["get", "post"]
    },
    {
      "path": "/api/v1/agents/{agent_id}",
      "methods": [
        {
          "method": "get",
          "tool_name": "get_agent_detail",
          "description": "Get agent details"
        }
      ]
    }
  ]
}

• 문자열 메서드: OpenAPI operationId를 Tool 이름으로 사용
• 객체 메서드: tool_name과 description 커스터마이징 가능
• api_maps만 사용 시 명시되지 않은 경로는 자동 제외 (MCPType.EXCLUDE)

Tool Output 전처리 (output)

객체 메서드에 output을 지정하면 백엔드 응답(JSON)을 클라이언트에 전달하기 전에 가공합니다:

{
  "method": "get",
  "tool_name": "get_articles",
  "output": {
    "include": ["items", "total"],
    "exclude": ["items.internal"],
    "transforms": [
      { "field": "items.body", "type": "html_to_markdown" }
    ]
  }
}

• include: 지정한 필드만 유지 (경로가 끝나는 지점의 하위 트리는 전체 유지)
• exclude: 지정한 필드 제거
• transforms: 문자열 필드 값을 변환. 지원 타입: html_to_markdown
• 적용 순서: include → exclude → transforms
• 필드 경로는 .으로 구분하며, 배열은 각 원소에 자동 적용 (items.body = items[*].body)
• 경로 기준은 Tool의 structured output입니다. 응답 최상위가 배열이면 FastMCP가 result 키로 감싸므로 result.<field> 형태로 지정
• output을 쓰려면 tool_name이 필수이며, include/exclude를 쓰는 Tool의 output schema는 Tool 목록에서 숨겨집니다
• tool_name은 FastMCP가 정규화(영숫자·_만 허용, 56자 제한)하므로, 등록된 Tool 이름과 다르면 설정이 적용되지 않고 경고 로그가 남습니다
• JSON이 아닌 응답(text 등)은 가공 없이 그대로 전달

route_maps (Pattern)

정규식 패턴으로 Tool을 필터링합니다:

{
  "route_maps": [
    {
      "pattern": "^/api/alert/v1/channels/.*",
      "methods": ["get"],
      "tags": []
    },
    {
      "pattern": "^/api/alert/v1/admin/.*",
      "methods": ["post"],
      "tags": ["alerts"]
    }
  ]
}

---

Docker

Build

docker build -t axmp-openapi-fastmcp-server .

Run

docker run -d \
  --env-file .env \
  -p 8000:8000 \
  -v /path/to/mcp_profiles:/application/mcp_profiles \
  axmp-openapi-fastmcp-server

Dockerfile Overview

FROM python:3.12.10-slim
WORKDIR /application

# Virtual env + uv install
RUN python -m venv /application/.venv && \
    /application/.venv/bin/pip install uv

# Install dependencies (production only)
COPY . .
RUN /application/.venv/bin/uv sync --no-cache --no-dev

# Container entry point (env-based)
CMD ["/application/.venv/bin/axmp-container-fastmcp-server"]

---

Development

Setup

# Install dev dependencies
uv sync

# Install pre-commit hooks
pre-commit install

Linting & Formatting

# Lint
uv run ruff check .

# Format
uv run ruff format .

Testing

# Run tests
uv run pytest

# Watch mode
uv run ptw

Pre-commit Hooks

Hook	Description
trailing-whitespace	후행 공백 제거
end-of-file-fixer	파일 끝 개행 보장
debug-statements	pdb import 감지
ruff	Lint & auto-fix
ruff-format	코드 포맷팅

---

CI/CD

GitHub Actions를 통해 semantic versioning 태그(v*.*.*) 푸시 시 자동 빌드 & 배포됩니다.

Pipeline

git tag v1.0.0 → push → GitHub Actions
                           ├─ Checkout
                           ├─ Setup QEMU (multi-arch)
                           ├─ Setup Docker Buildx
                           ├─ Login to Private Registry
                           ├─ Extract metadata (semver tags)
                           └─ Build & Push (linux/amd64, linux/arm64)

Registry

• Registry: zcr.cloudzcp.net
• Image: zcr.cloudzcp.net/cloudzcp/axmp-openapi-fastmcp-server
• Platforms: linux/amd64, linux/arm64

---

Tech Stack

Category	Technology
Language	Python 3.12+
MCP Framework	FastMCP >= 4.0.3
Settings	Pydantic Settings
HTTP Client	httpx2 (async)
CLI	Click
OAuth	Keycloak / Google / GitHub / Azure
Encryption	Fernet (cryptography)
Build	uv
Linting	Ruff
Container	Docker (multi-arch)
CI/CD	GitHub Actions

---

Author

Kilsoo Kang — kilsoo75@gmail.com