OpenAPI MCP Server

Servidor MCP (Model Context Protocol) que permite a un agente consultar la documentación OpenAPI de un backend en tiempo real.

Requisitos

• Python 3.12+
• Docker

Instalación

Con Docker (recomendado)

cd openapi_mcp
docker build -t openapi-mcp .

Entorno local (alternativa)

cd openapi_mcp
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Configuración

Opción 1: Variable de entorno (más sencilla)

Configura tu backend directamente en el JSON del agente MCP usando la variable OPENAPI_SERVICES con formato nombre:url,nombre2:url:

{
  "mcpServers": {
    "openapi": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "OPENAPI_SERVICES=mi-backend:http://host.docker.internal:8080/v3/api-docs",
        "openapi-mcp"
      ]
    }
  }
}

Si tu backend está en localhost, usa host.docker.internal para que el contenedor pueda llegar a él.

Para múltiples backends:

{
  "mcpServers": {
    "openapi": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "OPENAPI_SERVICES=mi-backend:http://host.docker.internal:8080/v3/api-docs,legacy:http://host.docker.internal:8081/v3/api-docs",
        "openapi-mcp"
      ]
    }
  }
}

Opción 2: Archivo YAML (alternativa)

Edita services.yaml con la URL de tu backend:

services:
  mi-backend: http://localhost:8080/v3/api-docs

Y monta el archivo como volumen al ejecutar Docker:

{
  "mcpServers": {
    "openapi": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/ruta/absoluta/a/openapi_mcp/services.yaml:/app/services.yaml",
        "openapi-mcp"
      ]
    }
  }
}

Ejecución

Con Docker

La ejecución va integrada en la configuración del agente. No necesitas ejecutar nada manualmente.

Entorno local

python server.py

Cómo funciona

Tu backend expone la especificación OpenAPI en una URL (por ejemplo, GET /v3/api-docs). El servidor MCP hace lo siguiente cuando una herramienta es invocada:

1. Lee la configuración: config.py carga la variable OPENAPI_SERVICES o el archivo services.yaml.
2. Descarga la especificación: loader.py hace una petición HTTP GET a la URL configurada y recibe el JSON de OpenAPI.
3. Procesa en memoria: tools.py convierte el JSON en un diccionario de Python y lo consulta directamente.
4. Sin persistencia: nunca se guarda el JSON en disco ni se mantiene en caché. Cada llamada descarga la especificación más reciente.

Registro en Claude Desktop

Edita el archivo de configuración de Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Usa la configuración Docker con variable de entorno que aparece arriba en Opción 1.

Reinicia Claude Desktop después de guardar la configuración.

Registro en Claude Code

Claude Code lee la configuración MCP desde ~/.mcp/config.json o desde archivos .mcp.json en el directorio de trabajo.

Configuración global

Crea ~/.mcp/config.json con la configuración Docker de Opción 1.

Configuración por proyecto

Crea un archivo .mcp.json en la raíz de tu proyecto con la misma configuración.

Claude Code detectará automáticamente el servidor MCP al iniciar.

Herramientas disponibles

Herramienta	Descripción
list_services()	Lista los backends configurados
list_endpoints(service)	Lista todos los endpoints de un backend
get_endpoint(service, method, path)	Devuelve la definición completa de un endpoint
search(query)	Busca texto en toda la documentación de todos los backends
get_schema(service, schema_name)	Devuelve la definición de un schema

Notas

• Sin caché: cada consulta descarga la especificación más reciente.
• Sin resolución de $ref: los schemas se devuelven tal como aparecen en el OpenAPI.
• Errores descriptivos: si un backend no responde, un path no existe o un schema no se encuentra, se devuelve un mensaje de error claro.

openapi-mcp