mcp-api-connect

Un payload de entrada, cualquier API de salida. mcp-api-connect es un motor de conectores agnóstico de protocolo y autenticación: describe un servicio de destino (URL, protocolo, autenticación, forma de solicitud/respuesta) una vez, luego envíale un payload normalizado y recibe una respuesta normalizada — ya sea que el destino sea una API REST/JSON, un servicio SOAP heredado, protegido por una clave de API, autenticación básica, un token Bearer o credenciales de cliente OAuth2.

Se distribuye como tres cosas construidas sobre el mismo motor central, así que como quieras usarlo, puedes:

• Una biblioteca de Python — pip install mcp-api-connect, llama a MCPAPIConnectEngine directamente, sin necesidad de servidor.

• Una API HTTP independiente — pip install mcp-api-connect[api], ejecuta mcp-api-connect-api, haz POST a /invoke.

• Un servidor MCP — pip install mcp-api-connect[mcp], ejecuta mcp-api-connect, apunta cualquier cliente MCP (Claude, etc.) hacia él para que un agente pueda llamar a conectores registrados — o servicios arbitrarios sobre la marcha — como herramientas.

Por qué

Cada proyecto de integración reinventa la misma rueda: un cliente REST aquí, un cliente SOAP allá, un flujo de autenticación por servicio, mapeo ad-hoc de solicitud/respuesta disperso por la base de código. mcp-api-connect centraliza eso en una especificación declarativa (InvokeSpec) y un motor de ejecución, de modo que añadir un nuevo servicio de destino es configuración, no código.

Related MCP server: Universal API Connector MCP

Inicio rápido (biblioteca)

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())

Inicio rápido (API HTTP)

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"}
}'

Registra un conector reutilizable una vez, luego invócalo por nombre:

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"}'

Inicio rápido (MCP)

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

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

Expone herramientas: invoke (sin estado, de una sola vez), register_connector, list_connectors, invoke_connector (por nombre), delete_connector. Un agente puede registrar un conector para "la API de Salesforce" una vez, y luego simplemente decir "llámalo con este payload" de ahí en adelante.

➜ Configuración completa para Claude Desktop / Claude Code / Cursor, persistencia, notas de seguridad y un ejemplo práctico: docs/mcp-integration.md.

Conceptos principales

• Target — URL base, protocolo (rest | soap), tiempo de espera, cabeceras por defecto.

• AuthSpec — type (none, api_key, basic, bearer, oauth2_client_credentials) + un dict config con la forma adecuada para ese tipo. Los tokens OAuth2 se obtienen y se almacenan en caché automáticamente.

• RequestFormat / ResponseFormat — tipo de contenido (json, xml, soap) más un field_map declarativo ({"target.path": "$.source.jsonpath"}) para remodelar payloads sin escribir código, o una body_template de Jinja2 para control total (requerida para sobres SOAP).

• InvokeSpec — agrupa los tres anteriores; la unidad de "cómo llegar a un servicio". Guárdalo como un Connector con nombre o pásalo en línea por llamada.

Consulta src/mcp_api_connect/core/models.py para el esquema completo, y docs/auth-reference.md para la forma de config que espera cada type de autenticación.

Documentación

• docs/mcp-integration.md — configuración completa del cliente MCP (Claude Desktop, Claude Code, Cursor), persistencia, seguridad, referencia de herramientas, ejemplo práctico, solución de problemas

• docs/auth-reference.md — campos de config para cada tipo de autenticación

• CONTRIBUTING.md — configuración de desarrollo, ejecución de pruebas, expectativas de PR

Extensión

• Nuevo tipo de autenticación: implementa AuthStrategy, regístralo mediante engine.register_auth_strategy(...).

• Nuevo protocolo (p. ej. GraphQL): implementa ProtocolAdapter, regístralo mediante engine.register_adapter(...).

• Nuevo backend de almacenamiento de conectores: implementa ConnectorStore (incluye InMemoryConnectorStore y SqliteConnectorStore, credenciales cifradas en reposo mediante Fernet).

Hoja de ruta

• Flujo de código de autorización OAuth2, mTLS, estrategias de autenticación AWS SigV4

• SOAP basado en WSDL (adaptador opcional respaldado por zeep, sin necesidad de sobre escrito a mano)

• Adaptador GraphQL

• ConnectorStore respaldado por Postgres

• Políticas de reintento/backoff + limitación de tasa por conector

• Lista blanca de destinos segura contra SSRF para despliegues públicos

Desarrollo

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

Licencia

MIT — consulta LICENSE.