mcp-registry

MLflow MCP Server Registry에 대한 작지만 완전한 엔드투엔드 워크스루입니다. FastMCP로 MCP 서버를 빌드하고, FastMCP 클라이언트로 호출한 다음, MLflow에 등록하여 버전, 액세스 엔드포인트, 자동 발견된 도구와 함께 발견 가능하게 만듭니다.

이 저장소는 세 가지 주요 부분으로 구성됩니다:

요구 사항

• Python ≥ 3.13

• 로컬에서 실행 중인 MLflow 추적 서버(v3.15+) — 레지스트리 API는 서버 측에 있습니다

• PostgreSQL (PostgreSQL 서버를 사용해보려는 경우)

• uv (저장소에는 uv.lock이 포함되어 있습니다)

의존성(pyproject.toml): fastmcp>=3.4.7, mlflow>=3.15.1, psycopg2 + psycopg2-binary, python-dotenv.

uv sync

Related MCP server: postgres-mcp-readonly

구성

PostgreSQL 서버는 연결 설정을 저장소 루트의 .env 파일에서 읽습니다(python-dotenv로 로드됨). .env는 gitignore되어 있습니다 — 직접 만드세요:

PGHOST=localhost
PGPORT=5432
PGUSER=root
PGPASSWORD=root
PGSSLMODE=prefer
PGADMINDB=postgres

src/simple_server.py는 구성이 필요 없습니다.

1. MLflow 추적 서버 시작

mlflow_mcp_registry_util.py는 http://127.0.0.1:5000을 가리킵니다. 저장소에는 이미 SQLite 백엔드 실행에서 생성된 mlflow.db(gitignore됨)가 포함되어 있습니다:

uv run mlflow server --backend-store-uri sqlite:///mlflow.db --host 127.0.0.1 --port 5000

서버가 다른 곳에 있다면 mlflow_mcp_registry_util.py 상단의 mlflow.set_tracking_uri(...) 호출을 수정하세요.

2. MCP 서버 실행

두 서버 모두 스트리밍 HTTP(http://localhost:8000/mcp)로 포트 8000에 바인딩되므로, 한 번에 하나씩 실행하세요 — 또는 mcp.run(...) 호출에서 포트를 변경하세요.

간단한 인사 서버 — Greeting 및 Sendoff라는 두 도구:

uv run python src/simple_server.py

PostgreSQL 탐색기 — 실행 중인 PostgreSQL 서버에 대한 읽기 전용 인트로스펙션:

uv run python src/postgresql_mcp.py

또는 FastMCP CLI를 통해:

uv run fastmcp run src/postgresql_mcp.py --transport http --port 8000

PostgreSQL 도구

모든 도구는 _query()를 통해 실행됩니다. _query()는 지정된 데이터베이스에 새 연결을 열고, RealDictCursor를 통해 단일 매개변수화된 SELECT를 실행한 후 연결을 닫습니다. 쓰기 작업은 없습니다.

3. 클라이언트에서 서버 호출

포트 8000에서 서버가 실행 중인 경우:

uv run python clients/postgres_server_client.py   # calls ListDatabases, prints each database name
uv run python clients/simple_server_client.py     # calls the greeting tool with "Ford"

clients/postgres_server_client.py는 FastMCP 결과를 언랩합니다. result.content의 각 항목은 JSON text 페이로드를 담고 있으며, 이를 파싱하여 database를 읽습니다.

참고: clients/simple_server_client.py는 client.call_tool("greet", ...)을 호출하지만, src/simple_server.py의 도구는 Greeting이라는 이름으로 등록되어 있습니다(greet는 Python 함수 이름일 뿐입니다). 호출이 해석되도록 "Greeting"을 사용하세요.

4. MLflow에 서버 등록

mlflow_mcp_registry_util.py에는 각각 하나의 레지스트리 API를 보여주는 네 개의 코루틴이 있습니다:

register_postgresql_mcp_server()

원격 서버 — 즉 이미 실행 중이고 HTTP를 통해 접근 가능한 서버를 등록합니다:

mlflow.genai.register_mcp_server(
    server_json={
        "name": "io.github.pavanjava/postgresql-server",
        "version": "0.1.0",
        "description": "PostgreSQL FastMCP server exposing DB tools",
        "remotes": [{"url": "http://localhost:8000/mcp", "type": "streamable-http"}],
    },
    status="active",
    source="local dev server via fastmcp",
    create_access_endpoints_from_remotes=True,
)

create_access_endpoints_from_remotes=True는 remotes의 각 항목을 MLflow 액세스 엔드포인트로 변환하므로, 소비자는 연결 URL을 하드코딩하는 대신 레지스트리에서 해결할 수 있습니다.

register_qdrant_mcp_server()

대신 패키징된 서버를 등록합니다 — 실행 중인 프로세스가 필요 없습니다. 항목은 실행 방법(stdio를 통한 uvx mcp-server-qdrant)을 설명하고 환경 변수를 선언하며, 필수 여부와 비밀 여부(QDRANT_API_KEY)를 포함합니다.

discover_tools()

refresh_mcp_server_version_tools(...)를 호출합니다. MLflow는 등록된 서버 버전에 연결하여 도구를 열거하고 버전에 저장합니다. 그 후 server_version.tools는 발견된 도구 이름을 나열합니다. 이 작업은 서버에 실제로 접근할 수 있어야 합니다.

list_endpoints()

search_mcp_access_endpoints(server_name=...)를 호출하고 각 엔드포인트의 URL, 전송 유형, 그리고 해석되는 서버 버전을 출력합니다.

실행

__main__ 블록은 한 번에 하나의 코루틴을 실행합니다. 나머지는 주석 처리되어 있습니다. 원하는 코루틴의 주석을 해제하세요:

if __name__ == "__main__":
    # asyncio.run(register_postgresql_mcp_server())
    asyncio.run(register_qdrant_mcp_server())
    # asyncio.run(discover_tools())
    # asyncio.run(list_endpoints())

uv run python mlflow_mcp_registry_util.py

등록된 서버는 http://127.0.0.1:5000의 MLflow UI에서 MCP Servers 섹션에 나타납니다.

권장 엔드투엔드 경로

1. 포트 5000에서 MLflow를 시작합니다.

2. 포트 8000에서 PostgreSQL MCP 서버를 시작합니다.

3. 응답을 확인합니다: uv run python clients/postgres_server_client.py.

4. 등록합니다: register_postgresql_mcp_server()의 주석을 해제하고 유틸리티를 실행합니다.

5. 도구를 발견합니다: discover_tools()로 전환하고 다시 실행합니다 — 위의 여섯 도구가 출력되어야 합니다.

6. 액세스 엔드포인트를 검사합니다: list_endpoints()로 전환합니다.

7. MLflow UI에서 결과를 확인합니다.

저장소 구조

.
├── src/
│   ├── simple_server.py        # FastMCP "My MCP Server" — Greeting + Sendoff tools
│   └── postgresql_mcp.py       # FastMCP "PostgreSQL Explorer" — 6 read-only introspection tools
├── clients/
│   ├── simple_server_client.py     # calls a tool on the greeting server
│   └── postgres_server_client.py   # calls ListDatabases and prints database names
├── mlflow_mcp_registry_util.py # MLflow MCP registry: register / refresh tools / list endpoints
├── pyproject.toml
└── uv.lock

mlflow.db, .env, .venv, .idea는 gitignore되어 있습니다.