mcp-api-connect

Один запрос на входе — любой API на выходе. mcp-api-connect — это движок коннекторов, не зависящий от протокола и аутентификации: опишите целевой сервис (URL, протокол, аутентификацию, форму запроса/ответа) один раз, затем отправьте ему нормализованный запрос и получите нормализованный ответ — будь то REST/JSON API, устаревший SOAP-сервис, защищённый API-ключом, Basic-аутентификацией, Bearer-токеном или OAuth2 client credentials.

Он поставляется в трёх вариантах, построенных на одном и том же ядре, так что вы можете использовать его так, как вам удобно:

• Библиотека Python — pip install mcp-api-connect, вызывайте MCPAPIConnectEngine напрямую, сервер не требуется.

• Автономный HTTP API — pip install mcp-api-connect[api], запустите mcp-api-connect-api, отправляйте POST на /invoke.

• MCP-сервер — pip install mcp-api-connect[mcp], запустите mcp-api-connect, укажите на него любому MCP-клиенту (Claude и т.д.), чтобы агент мог вызывать зарегистрированные коннекторы — или произвольные сервисы на лету — как инструменты.

Зачем

Каждый интеграционный проект заново изобретает велосипед: где-то REST-клиент, где-то SOAP-клиент, отдельный поток аутентификации для каждого сервиса, ad-hoc сопоставление запросов/ответов, разбросанное по кодовой базе. 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"}) для изменения формы запросов без написания кода, или body_template на Jinja2 для полного контроля (обязателен для SOAP-конвертов).

• InvokeSpec — объединяет три вышеперечисленных; единица «как достичь одного сервиса». Храните его как именованный Connector или передавайте встроенно при каждом вызове.

Полную схему см. в src/mcp_api_connect/core/models.py, а форму config, которую ожидает каждый type аутентификации, — в 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

• SOAP на основе WSDL (опциональный адаптер на zeep, без ручного написания конверта)

• Адаптер GraphQL

• ConnectorStore на базе Postgres

• Политики повторных попыток/backoff и ограничения скорости для каждого коннектора

• Безопасный от SSRF список разрешённых целевых адресов для публичных развёртываний

Разработка

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

Лицензия

MIT — см. LICENSE.