Zyla API Hub MCP Server

Servidor MCP de Zyla API Hub

Un servidor MCP (Model Context Protocol) que le da a cualquier agente de IA la capacidad de llamar a cualquier API en el Zyla API Hub — con una sola herramienta.

Zyla API Hub • Explorar APIs • Obtener una clave de API

Conectas este servidor a tu agente de IA (Claude, Cursor, OpenClaw, OpenAI Agents, etc.), y el agente aprende automáticamente cómo hacer solicitudes HTTP a cualquier endpoint de la API de Zyla. No se necesita código personalizado.

Construido con el SDK oficial de MCP para Python (v1.x).

---

Tabla de Contenidos

• Cómo Funciona (Explicación Simple)
• Inicio Rápido (3 Pasos)
• Conexión a Agentes de IA
  • Claude Desktop
  • Claude Code (CLI)
  • Cursor IDE
  • OpenClaw
  • OpenAI Agents SDK
  • LangChain
  • Agente Python Personalizado
  • Agente de Red SSE
  • MCP Inspector (Pruebas)
• Lo que Ve el Agente
• Ejemplos de Uso
• Despliegue con Docker
• Estructura del Proyecto
• Solución de Problemas
• Licencia

---

Cómo Funciona (Explicación Simple)

You (human)             AI Agent               This MCP Server           Zyla API Hub
     │                     │                        │                        │
     │  "Get crime data    │                        │                        │
     │   for zip 90210"    │                        │                        │
     │ ──────────────────► │                        │                        │
     │                     │  call_api(GET, url,    │                        │
     │                     │  headers, params)      │                        │
     │                     │ ─────────────────────► │   HTTP GET             │
     │                     │                        │ ─────────────────────► │
     │                     │                        │   JSON response        │
     │                     │                        │ ◄───────────────────── │
     │                     │  {status: 200,         │                        │
     │                     │   response: {...}}     │                        │
     │                     │ ◄───────────────────── │                        │
     │  "Crime grade is    │                        │                        │
     │   B+ for 90210..."  │                        │                        │
     │ ◄────────────────── │                        │                        │

En palabras simples:

1. Le haces una pregunta a tu agente de IA (en lenguaje natural).
2. El agente decide que necesita llamar a una API y usa la herramienta call_api de este servidor.
3. Este servidor hace la solicitud HTTP al Zyla API Hub y devuelve los datos.
4. El agente lee los datos y te responde en lenguaje natural.

El agente determina qué API llamar, qué parámetros usar y cómo interpretar los resultados — todo por sí solo. Tú solo haces la pregunta.

---

Inicio Rápido (3 Pasos)

1. Instalar

git clone https://github.com/zyla-labs/zyla-api-hub-mcp.git
cd zyla-api-hub-mcp
pip install -r requirements.txt

2. Ejecutar

python mcp_server.py

3. Conecta tu agente de IA

Elige tu agente de la lista a continuación y sigue la configuración única. Después de eso, solo chatea normalmente — el agente usará las APIs de Zyla cuando sea necesario.

---

Conexión a Agentes de IA

Claude Desktop

Agrega a tu archivo de configuración (claude_desktop_config.json):

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

{
  "mcpServers": {
    "zyla-api-hub": {
      "command": "python",
      "args": ["/absolute/path/to/mcp_server.py"],
      "env": {}
    }
  }
}

Reinicia Claude Desktop. Verás un ícono de martillo en el chat — eso significa que la herramienta está disponible. Solo pregunta:

"Usa la API de Zyla para obtener las tasas de criminalidad del código postal 90210. Mi clave de API es Bearer sk-zyla..."

---

Claude Code (CLI)

claude mcp add zyla-api-hub -- python /absolute/path/to/mcp_server.py

Luego chatea normalmente. Claude Code invocará call_api cuando necesite llamar a una API.

---

Cursor IDE

Agrega a .cursor/mcp.json en tu proyecto (o en la configuración global de Cursor):

{
  "mcpServers": {
    "zyla-api-hub": {
      "command": "python",
      "args": ["/absolute/path/to/mcp_server.py"]
    }
  }
}

En el modo Agente de Cursor, la IA usará call_api cuando le pidas que obtenga datos de una API.

---

OpenClaw

OpenClaw es una puerta de enlace de agentes de IA autoalojada que admite múltiples canales de chat (WhatsApp, Telegram, Slack, Discord, iMessage, etc.) y puede usar herramientas externas a través de MCP.

Opción A — Agregar vía CLI (recomendado):

openclaw mcp add --transport stdio zyla-api-hub python /absolute/path/to/mcp_server.py

Esto registra el servidor MCP para que el agente de OpenClaw pueda descubrir y usar la herramienta call_api.

Opción B — Agregar vía configuración (~/.openclaw/openclaw.json):

Si prefieres la configuración manual, agrega el servidor MCP en tu configuración de OpenClaw:

{
  // ... your existing openclaw.json config ...
  "mcpServers": {
    "zyla-api-hub": {
      "command": "python",
      "args": ["/absolute/path/to/mcp_server.py"],
      "transport": "stdio"
    }
  }
}

Luego reinicia la puerta de enlace:

openclaw gateway restart

Opción C — Docker + SSE (despliegue en red):

Si tu puerta de enlace de OpenClaw se ejecuta en un servidor remoto o en Docker, usa el transporte SSE:

# Start the MCP server with SSE transport
docker run -p 8000:8000 -e MCP_TRANSPORT=sse ghcr.io/zyla-labs/mcp-server:latest

# Then register it in OpenClaw pointing to the network URL
openclaw mcp add --transport sse zyla-api-hub http://localhost:8000/sse

Uso:

Una vez conectado, chatea con tu agente de OpenClaw a través de cualquier canal (WhatsApp, Slack, Telegram, etc.) y automáticamente usará la API de Zyla cuando sea necesario:

You (via WhatsApp): "What's the weather like in Buenos Aires?"

OpenClaw agent → calls call_api(
  method="GET",
  url="https://www.zylalabs.com/api/.../weather",
  headers={"Authorization": "Bearer sk-zyla..."},
  params={"city": "Buenos Aires"}
)

OpenClaw agent: "It's currently 18C and partly cloudy in Buenos Aires."

Para más información sobre la configuración de OpenClaw, consulta la guía de inicio.

---

OpenAI Agents SDK

El OpenAI Agents SDK admite servidores MCP como proveedores de herramientas de forma nativa:

from agents import Agent
from agents.mcp import MCPServerStdio

async with MCPServerStdio(
    command="python",
    args=["/absolute/path/to/mcp_server.py"],
) as mcp_server:
    agent = Agent(
        name="Zyla Assistant",
        instructions="You can call any API on the Zyla API Hub using the call_api tool.",
        mcp_servers=[mcp_server],
    )
    # The agent now has access to call_api

---

LangChain

Usa el Adaptador MCP de LangChain para envolver herramientas MCP como herramientas de LangChain:

from langchain_mcp_adapters.client import MultiServerMCPClient

async with MultiServerMCPClient({
    "zyla-api-hub": {
        "command": "python",
        "args": ["/absolute/path/to/mcp_server.py"],
        "transport": "stdio",
    }
}) as client:
    tools = client.get_tools()
    # Use tools with any LangChain agent

---

Agente Python Personalizado

Construye tu propio agente usando el SDK oficial de MCP para Python:

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    # 1. Point to the MCP server
    server_params = StdioServerParameters(
        command="python",
        args=["mcp_server.py"],
    )

    # 2. Connect
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # 3. See available tools
            tools = await session.list_tools()
            print("Tools:", [t.name for t in tools.tools])
            # Output: Tools: ['call_api']

            # 4. Call an API
            result = await session.call_tool("call_api", arguments={
                "method": "GET",
                "url": "https://www.zylalabs.com/api/824/crime+data+by+zipcode+api/583/get+crime+rates+by+zip",
                "headers": {"Authorization": "Bearer YOUR_ZYLA_API_KEY"},
                "params": {"zip": "90210"},
            })

            # 5. Read the response
            print("Status:", result.structured_content["status_code"])
            print("Data:", result.structured_content["response"])

asyncio.run(main())

---

Agente de Red SSE

Para agentes que se conectan a través de HTTP (aplicaciones web, microservicios, despliegues remotos):

# Start the server with SSE transport first
python mcp_server.py sse

import asyncio
from mcp import ClientSession
from mcp.client.sse import sse_client

async def main():
    async with sse_client("http://localhost:8000/sse") as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            result = await session.call_tool("call_api", arguments={
                "method": "GET",
                "url": "https://www.zylalabs.com/api/XXXX/your+api/YYY/endpoint",
                "headers": {"Authorization": "Bearer YOUR_KEY"},
            })
            print(result.structured_content)

asyncio.run(main())

---

MCP Inspector (Pruebas)

El MCP Inspector te permite probar el servidor de forma interactiva en un navegador:

# Terminal 1: start the server
python mcp_server.py sse

# Terminal 2: start the inspector
npx -y @modelcontextprotocol/inspector

Abre la interfaz del Inspector y conéctate a http://localhost:8000/sse. Puedes explorar el esquema de la herramienta e invocar call_api manualmente.

---

Lo que Ve el Agente

Cuando un agente de IA se conecta, recibe automáticamente este esquema de herramienta a través del protocolo MCP:

Nombre de la herramienta: call_api

Descripción (leída por el LLM):

Llama a cualquier endpoint de API del Zyla API Hub. Admite GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS. Incluye siempre un encabezado Authorization con tu clave de API de Zyla.

Parámetros de entrada:

Parámetro	Tipo	Obligatorio	Qué hace
method	string	Sí	Método HTTP (GET, POST, PUT, DELETE, PATCH, etc.)
url	string	Sí	URL completa del endpoint de la API
headers	dict[str, str]	No	Encabezados HTTP (incluye Authorization aquí)
params	dict[str, str]	No	Parámetros de cadena de consulta (enviados en todos los métodos)
data	dict	No	Cuerpo JSON (solo para POST, PUT, PATCH)

Salida (estructurada):

Campo	Tipo	Qué significa
status_code	int	Código de estado HTTP (200, 404, etc.). 0 = la solicitud no llegó al servidor
response	str | dict | list	Cuerpo JSON analizado, o texto sin procesar si no es JSON
error	str | null	Mensaje de error si algo salió mal; null en caso de éxito

---

Ejemplos de Uso

GET simple

{
  "method": "GET",
  "url": "https://www.zylalabs.com/api/824/crime+data+by+zipcode+api/583/get+crime+rates+by+zip",
  "headers": { "Authorization": "Bearer YOUR_ZYLA_API_KEY" },
  "params": { "zip": "90210" }
}

POST con cuerpo JSON

{
  "method": "POST",
  "url": "https://www.zylalabs.com/api/XXXX/some+api/YYY/endpoint",
  "headers": {
    "Authorization": "Bearer YOUR_ZYLA_API_KEY",
    "Content-Type": "application/json"
  },
  "data": { "input_text": "Hello, world!", "language": "en" }
}

POST con parámetros de consulta + cuerpo

{
  "method": "POST",
  "url": "https://www.zylalabs.com/api/XXXX/some+api/YYY/search",
  "headers": { "Authorization": "Bearer YOUR_ZYLA_API_KEY" },
  "params": { "page": "1", "limit": "10" },
  "data": { "query": "machine learning" }
}

Respuesta de éxito

{
  "status_code": 200,
  "response": { "data": "...", "count": 42 },
  "error": null
}

Respuesta de error

{
  "status_code": 0,
  "response": "",
  "error": "Request timed out after 30 seconds"
}

---

Despliegue con Docker

Construir

docker build -t zyla-mcp-server .

Ejecutar (stdio — para agentes locales)

docker run -i zyla-mcp-server

Ejecutar (SSE — para agentes de red)

docker run -p 8000:8000 -e MCP_TRANSPORT=sse zyla-mcp-server

Imagen preconstruida

docker pull ghcr.io/zyla-labs/mcp-server:latest
docker run -p 8000:8000 -e MCP_TRANSPORT=sse ghcr.io/zyla-labs/mcp-server:latest

El pipeline de CI publica automáticamente en GitHub Container Registry en cada push a master.

---

Estructura del Proyecto

zyla-api-hub-mcp/
├── mcp_server.py          # MCP server (single file, all logic)
├── pyproject.toml          # Python packaging (PEP 621)
├── requirements.txt        # Pinned dependencies
├── Dockerfile              # Docker image
├── .dockerignore
├── .github/
│   └── workflows/
│       └── publish.yml     # CI/CD → GHCR
└── README.md

Dependencias: mcp[cli]>=1.26.0, httpx>=0.27.0 — eso es todo.

Decisiones de diseño clave:

• SDK oficial mcp (mcp.server.fastmcp.FastMCP), no el paquete de terceros fastmcp
• httpx en lugar de requests (compatible con async, alineado con el ecosistema MCP)
• Modelo Pydantic ApiResponse para salida estructurada (los LLM obtienen un esquema JSON tipado)
• Sin argumentos predeterminados mutables (None en lugar de {})
• Manejo de errores granular (tiempo de espera, error de solicitud, error inesperado — cada uno con un mensaje claro)
• Parámetros de consulta enviados en todos los métodos HTTP (no solo GET)
• Transporte seleccionable mediante argumento CLI (stdio o sse)

---

Solución de Problemas

Problema	Solución
ModuleNotFoundError: No module named 'mcp'	Ejecuta pip install -r requirements.txt
El servidor inicia pero el agente no puede ver la herramienta	Asegúrate de usar el transporte correcto. Los agentes locales (Claude Desktop, Cursor) usan stdio (predeterminado). Los agentes de red usan sse.
Errores de tiempo de espera de solicitud	El tiempo de espera predeterminado es de 30 segundos. Si la API de Zyla upstream es lenta, recibirás un mensaje de error claro.
Docker SSE "conexión rechazada"	Expón el puerto: docker run -p 8000:8000 -e MCP_TRANSPORT=sse zyla-mcp-server
OpenClaw no ve la herramienta	Reinicia la puerta de enlace después de agregar el servidor MCP: openclaw gateway restart

---

Licencia

MIT