kobra-api-mcp

MCP server para que cualquier IA (Grok, Cursor, Claude Desktop, etc.) use la API Kobra de verdad:

1. Lee el OpenAPI live (no un PDF viejo)
2. Sabe cómo autenticarse (partner key, bearer, session)
3. Ejecuta requests HTTP y devuelve status + body

Default: https://stage.api.trykobra.com. Prod solo con KOBRA_ALLOW_PROD=1.

Install

cd kobra-api-mcp
uv sync
# o: pip install -e .

Run (stdio MCP)

export KOBRA_ENV=stage
export KOBRA_PARTNER_KEY='kbr_…'   # para /api/partner/v1/*
uv run python -m kobra_api_mcp

Config para Grok / Cursor / Claude

Ver config/grok-mcp.example.json y config/cursor-mcp.example.json.

Ejemplo Cursor (~/.cursor/mcp.json o settings MCP):

{
  "mcpServers": {
    "kobra-api": {
      "command": "uv",
      "args": ["run", "--directory", "/ABS/PATH/kobra-api-mcp", "python", "-m", "kobra_api_mcp"],
      "env": {
        "KOBRA_ENV": "stage",
        "KOBRA_ALLOW_PROD": "0",
        "KOBRA_PARTNER_KEY": "kbr_…"
      }
    }
  }
}

Grok (sesiones con MCP): mismo bloque mcpServers en la config de MCP del host que use Grok Build / TUI. La key nunca va en el chat: solo en env del server.

Auth (lo que la IA debe saber)

Perfil	Env	Header	Rutas
none	—	—	/health, /docs, /openapi.json, /sdk, /api/catalog*, /partner/docs
partner	KOBRA_PARTNER_KEY	X-Kobra-Partner-Key (o Authorization: Partner <key>)	/api/partner/v1/*
bearer	KOBRA_BEARER_TOKEN	Authorization: Bearer …	si aplica
session	KOBRA_SESSION_COOKIE	Cookie: …	team/portal
auto	(elige)	según path	default en call_route

Tools:

• auth_profiles — qué está configurado
• call_route(..., auth_profile="auto"|"partner"|…) — prueba real

Tools

Tool	Uso
api_info	base URL, auth flags, links a docs humanas
auth_profiles	cómo autenticar cada perfil
refresh_openapi	re-baja OpenAPI full + partner
list_routes	filtrar method/tag/q
get_route	detalle + schema + auth_hint
call_route	HTTP real
smoke_public	health + docs sin auth
smoke_partner	/me + /summary con key
suggest_probe_plan	plan de pruebas ordenado
docs_urls	atajos Scalar/SDK

Flujo recomendado para la IA

1. api_info()
2. auth_profiles()
3. refresh_openapi()
4. list_routes(q="partner") o suggest_probe_plan(focus="partner")
5. get_route("GET", "/api/partner/v1/me")
6. call_route("GET", "/api/partner/v1/me", auth_profile="partner")
7. call_route writes solo en stage, con body del schema

Docs humanas (mismo backend)

URL	Qué
{base}/docs	Scalar API completa
{base}/partner/docs	Scalar Partner
{base}/sdk	SDK Python
{base}/openapi.json	Schema full
{base}/api/partner/v1/openapi.json	Schema partner

Defaults:

• stage: https://stage.api.trykobra.com
• prod: https://api.trykobra.com (+ KOBRA_ALLOW_PROD=1)

Tests

uv run pytest -q
KOBRA_MCP_LIVE=1 uv run pytest -q tests/test_client_live_optional.py

Seguridad

• Secretos solo en env del proceso MCP
• Headers sensibles se devuelven redactados al modelo
• Prod bloqueado por default
• No hay tool para “guardar” keys desde el chat

Licencia

MIT