Zyla API Hub MCP Server

Servidor MCP do Zyla API Hub

Um servidor MCP (Model Context Protocol) que dá a qualquer agente de IA a capacidade de chamar qualquer API no Zyla API Hub — com uma única ferramenta.

Zyla API Hub • Explorar APIs • Obter uma Chave de API

Você conecta este servidor ao seu agente de IA (Claude, Cursor, OpenClaw, OpenAI Agents, etc.), e o agente aprende automaticamente como fazer requisições HTTP para qualquer endpoint da API Zyla. Nenhum código personalizado é necessário.

Construído com o SDK Python oficial do MCP (v1.x).

---

Sumário

• Como Funciona (Explicação Simples)
• Início Rápido (3 Passos)
• Conectando a Agentes de IA
  • Claude Desktop
  • Claude Code (CLI)
  • Cursor IDE
  • OpenClaw
  • OpenAI Agents SDK
  • LangChain
  • Agente Python Personalizado
  • Agente de Rede SSE
  • MCP Inspector (Testes)
• O que o Agente Vê
• Exemplos de Uso
• Implantação com Docker
• Estrutura do Projeto
• Solução de Problemas
• Licença

---

Como Funciona (Explicação Simples)

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..."  │                        │                        │
     │ ◄────────────────── │                        │                        │

Em palavras simples:

1. Você faz uma pergunta ao seu agente de IA (em linguagem natural).
2. O agente decide que precisa chamar uma API e usa a ferramenta call_api deste servidor.
3. Este servidor faz a requisição HTTP ao Zyla API Hub e retorna os dados.
4. O agente lê os dados e responde em linguagem natural.

O agente descobre qual API chamar, quais parâmetros usar e como interpretar os resultados — tudo sozinho. Você apenas faz a pergunta.

---

Início Rápido (3 Passos)

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. Executar

python mcp_server.py

3. Conectar seu agente de IA

Escolha seu agente na lista abaixo e siga a configuração única. Depois disso, basta conversar normalmente — o agente usará as APIs Zyla quando necessário.

---

Conectando a Agentes de IA

Claude Desktop

Adicione ao seu arquivo de configuração (claude_desktop_config.json):

SO	Caminho
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": {}
    }
  }
}

Reinicie o Claude Desktop. Você verá um ícone de martelo no chat — isso significa que a ferramenta está disponível. Basta perguntar:

"Use a API Zyla para obter as taxas de criminalidade para o CEP 90210. Minha chave de API é Bearer sk-zyla..."

---

Claude Code (CLI)

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

Depois, converse normalmente. O Claude Code invocará call_api quando precisar chamar uma API.

---

Cursor IDE

Adicione a .cursor/mcp.json no seu projeto (ou nas configurações globais do Cursor):

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

No modo Agente do Cursor, a IA usará call_api quando você pedir para buscar dados de uma API.

---

OpenClaw

OpenClaw é um gateway de agente de IA auto-hospedado que suporta múltiplos canais de chat (WhatsApp, Telegram, Slack, Discord, iMessage, etc.) e pode usar ferramentas externas via MCP.

Opção A — Adicionar via CLI (recomendado):

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

Isso registra o servidor MCP para que o agente OpenClaw possa descobrir e usar a ferramenta call_api.

Opção B — Adicionar via configuração (~/.openclaw/openclaw.json):

Se preferir configuração manual, adicione o servidor MCP na sua configuração do OpenClaw:

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

Depois, reinicie o gateway:

openclaw gateway restart

Opção C — Docker + SSE (implantação em rede):

Se o seu gateway OpenClaw roda em um servidor remoto ou em Docker, use 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

Usando:

Depois de conectado, converse com seu agente OpenClaw por qualquer canal (WhatsApp, Slack, Telegram, etc.) e ele usará automaticamente a API Zyla quando necessário:

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 mais informações sobre a configuração do OpenClaw, veja o guia de Introdução.

---

OpenAI Agents SDK

O OpenAI Agents SDK suporta servidores MCP como provedores de ferramentas nativamente:

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

Use o Adaptador MCP do LangChain para transformar ferramentas MCP em ferramentas 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

Construa seu próprio agente usando o SDK Python oficial do MCP:

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 Rede SSE

Para agentes que se conectam via HTTP (aplicações web, microsserviços, implantações remotas):

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

O MCP Inspector permite testar o servidor interativamente em um navegador:

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

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

Abra a interface do Inspector e conecte-se a http://localhost:8000/sse. Você pode navegar pelo esquema da ferramenta e invocar call_api manualmente.

---

O que o Agente Vê

Quando um agente de IA se conecta, ele recebe automaticamente este esquema de ferramenta via protocolo MCP:

Nome da ferramenta: call_api

Descrição (lida pelo LLM):

Chame qualquer endpoint de API do Zyla API Hub. Suporta GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS. Sempre inclua um cabeçalho Authorization com sua chave de API Zyla.

Parâmetros de entrada:

Parâmetro	Tipo	Obrigatório	O que faz
method	string	Sim	Método HTTP (GET, POST, PUT, DELETE, PATCH, etc.)
url	string	Sim	URL completa do endpoint da API
headers	dict[str, str]	Não	Cabeçalhos HTTP (inclua Authorization aqui)
params	dict[str, str]	Não	Parâmetros de query-string (enviados em todos os métodos)
data	dict	Não	Corpo JSON (apenas para POST, PUT, PATCH)

Saída (estruturada):

Campo	Tipo	O que significa
status_code	int	Código de status HTTP (200, 404, etc.). 0 = a requisição não chegou ao servidor
response	str | dict | list	Corpo JSON analisado, ou texto bruto se não for JSON
error	str | null	Mensagem de erro se algo der errado; null em caso de sucesso

---

Exemplos de Uso

GET simples

{
  "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 com corpo 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 com parâmetros de query + corpo

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

Resposta de sucesso

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

Resposta de erro

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

---

Implantação com Docker

Construir

docker build -t zyla-mcp-server .

Executar (stdio — para agentes locais)

docker run -i zyla-mcp-server

Executar (SSE — para agentes de rede)

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

Imagem pré-construída

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

O pipeline de CI publica automaticamente no GitHub Container Registry a cada push para master.

---

Estrutura do Projeto

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

Dependências: mcp[cli]>=1.26.0, httpx>=0.27.0 — só isso.

Principais decisões de design:

• SDK oficial mcp (mcp.server.fastmcp.FastMCP), não o pacote de terceiros fastmcp
• httpx em vez de requests (pronto para async, alinhado com o ecossistema MCP)
• Modelo Pydantic ApiResponse para saída estruturada (LLMs recebem um esquema JSON tipado)
• Sem argumentos padrão mutáveis (None em vez de {})
• Tratamento de erros granular (timeout, erro de requisição, erro inesperado — cada um com mensagem clara)
• Parâmetros de query enviados em todos os métodos HTTP (não apenas GET)
• Transporte selecionável via argumento de CLI (stdio ou sse)

---

Solução de Problemas

Problema	Solução
ModuleNotFoundError: No module named 'mcp'	Execute pip install -r requirements.txt
O servidor inicia, mas o agente não vê a ferramenta	Certifique-se de que está usando o transporte correto. Agentes locais (Claude Desktop, Cursor) usam stdio (padrão). Agentes de rede usam sse.
Erros de timeout de requisição	O timeout padrão é de 30 segundos. Se a API Zyla upstream estiver lenta, você receberá uma mensagem de erro clara.
Docker SSE "connection refused"	Exponha a porta: docker run -p 8000:8000 -e MCP_TRANSPORT=sse zyla-mcp-server
OpenClaw não vê a ferramenta	Reinicie o gateway após adicionar o servidor MCP: openclaw gateway restart

---

Licença

MIT