mcp-api-connect

하나의 페이로드로 어떤 API든 연결합니다. mcp-api-connect는 프로토콜과 인증 방식에 구애받지 않는 커넥터 엔진입니다. 대상 서비스(URL, 프로토콜, 인증, 요청/응답 형태)를 한 번 정의하면, 정규화된 페이로드를 보내고 정규화된 응답을 받을 수 있습니다. 대상이 REST/JSON API든, 레거시 SOAP 서비스든, API 키, Basic 인증, Bearer 토큰, 또는 OAuth2 클라이언트 자격 증명으로 보호되든 상관없습니다.

이 프로젝트는 동일한 핵심 엔진을 기반으로 세 가지 형태로 제공되므로, 원하는 방식으로 사용할 수 있습니다:

• Python 라이브러리 — pip install mcp-api-connect, 서버 없이 MCPAPIConnectEngine을 직접 호출합니다.

• 독립형 HTTP API — pip install mcp-api-connect[api], mcp-api-connect-api를 실행하고 /invoke에 POST 요청을 보냅니다.

• MCP 서버 — pip install mcp-api-connect[mcp], mcp-api-connect를 실행하고, 어떤 MCP 클라이언트(Claude 등)든 연결하여 에이전트가 등록된 커넥터를 호출하거나 즉석에서 임의의 서비스를 도구로 호출할 수 있게 합니다.

왜 필요한가

모든 통합 프로젝트는 같은 바퀴를 다시 발명합니다. 여기 REST 클라이언트, 저기 SOAP 클라이언트, 서비스마다 하나씩의 인증 흐름, 코드베이스 곳곳에 흩어진 임시 요청/응답 매핑. mcp-api-connect는 이를 하나의 선언적 스펙(InvokeSpec)과 하나의 실행 엔진으로 중앙화하여, 새 대상 서비스를 추가하는 것이 코드가 아닌 설정이 되게 합니다.

Related MCP server: Universal API Connector MCP

빠른 시작 (라이브러리)

pip install mcp-api-connect

import asyncio
from mcp_api_connect import MCPAPIConnectEngine, InvokeSpec, Target, AuthSpec, AuthType, RequestFormat, ResponseFormat

spec = InvokeSpec(
    target=Target(base_url="https://api.example.com"),
    auth=AuthSpec(type=AuthType.API_KEY, config={"api_key": "secret", "header_name": "X-API-Key"}),
    request_format=RequestFormat(method="POST", path="/v1/orders", content_type="json"),
    response_format=ResponseFormat(content_type="json"),
)

async def main():
    async with MCPAPIConnectEngine() as engine:
        result = await engine.invoke(spec, {"customer": "jane"})
        print(result.success, result.data)

asyncio.run(main())

빠른 시작 (HTTP API)

pip install "mcp-api-connect[api]"
mcp-api-connect-api   # serves on :8000, interactive docs at /docs

curl -X POST http://localhost:8000/invoke -H 'content-type: application/json' -d '{
  "spec": {
    "target": {"base_url": "https://api.example.com"},
    "auth": {"type": "api_key", "config": {"api_key": "secret"}},
    "request_format": {"method": "POST", "path": "/v1/orders"},
    "response_format": {"content_type": "json"}
  },
  "payload": {"customer": "jane"}
}'

재사용 가능한 커넥터를 한 번 등록한 후 이름으로 호출합니다:

curl -X POST http://localhost:8000/connectors -d '{"name": "orders-api", "spec": {...}}'
curl -X POST http://localhost:8000/connectors/orders-api/invoke -d '{"customer": "jane"}'

빠른 시작 (MCP)

pip install "mcp-api-connect[mcp]"

{
  "mcpServers": {
    "mcp-api-connect": { "command": "/path/to/.venv/bin/mcp-api-connect" }
  }
}

다음 도구를 노출합니다: invoke(상태 없는 일회성), register_connector, list_connectors, invoke_connector(이름으로), delete_connector. 에이전트는 "Salesforce API"용 커넥터를 한 번 등록한 후, 이후에는 "이 페이로드로 호출해"라고 말하기만 하면 됩니다.

➜ Claude Desktop / Claude Code / Cursor 전체 설정, 영속성, 보안 참고 사항, 그리고 실제 예제: docs/mcp-integration.md.

핵심 개념

• Target — 기본 URL, 프로토콜(rest | soap), 타임아웃, 기본 헤더.

• AuthSpec — type(none, api_key, basic, bearer, oauth2_client_credentials) + 해당 유형에 맞는 config 딕셔너리. OAuth2 토큰은 자동으로 가져와 캐시됩니다.

• RequestFormat / ResponseFormat — 콘텐츠 유형(json, xml, soap)과 선언적 field_map({"target.path": "$.source.jsonpath"})을 통해 코드 작성 없이 페이로드를 재구성하거나, 완전한 제어를 위한 Jinja2 body_template(SOAP 봉투에 필수)을 지원합니다.

• InvokeSpec — 위 세 가지를 묶은 것으로, "하나의 서비스에 도달하는 방법"의 단위입니다. 이름 있는 Connector로 저장하거나 호출 시 인라인으로 전달할 수 있습니다.

전체 스키마는 src/mcp_api_connect/core/models.py를, 각 인증 type이 기대하는 config 형태는 docs/auth-reference.md를 참조하세요.

문서

• docs/mcp-integration.md — 전체 MCP 클라이언트 설정(Claude Desktop, Claude Code, Cursor), 영속성, 보안, 도구 참조, 실제 예제, 문제 해결

• docs/auth-reference.md — 모든 인증 유형의 config 필드

• CONTRIBUTING.md — 개발 환경 설정, 테스트 실행, PR 기대 사항

확장

• 새 인증 유형: AuthStrategy를 구현하고 engine.register_auth_strategy(...)로 등록합니다.

• 새 프로토콜(예: GraphQL): ProtocolAdapter를 구현하고 engine.register_adapter(...)로 등록합니다.

• 새 커넥터 저장소 백엔드: ConnectorStore를 구현합니다(InMemoryConnectorStore와 SqliteConnectorStore가 포함되며, 자격 증명은 Fernet으로 암호화되어 저장됩니다).

로드맵

• OAuth2 인가 코드 흐름, mTLS, AWS SigV4 인증 전략

• WSDL 기반 SOAP(선택적 zeep 기반 어댑터, 수동 봉투 작성 불필요)

• GraphQL 어댑터

• Postgres 기반 ConnectorStore

• 커넥터별 재시도/백오프 및 속도 제한 정책

• 공개 배포를 위한 SSRF 안전 대상 허용 목록

개발

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,api,storage,mcp]"
pytest

라이선스

MIT — LICENSE 참조.