Saltar al contenido

Guía de instalación

Ponte en marcha en menos de 5 minutos. Esta guía incluye la configuración para 23 clientes MCP, entre ellos Claude Code, Claude Desktop, Cursor, VS Code / GitHub Copilot, y Devin Desktop (Windsurf), y más.

Requisitos previos: necesitarás una clave de API de app.maguyva.ai y un repositorio de GitHub conectado.

Configuración del entorno

#

Primero, configura la clave de API en una variable de entorno. Omite repository cuando el cliente MCP proporcione un valor predeterminado para la solicitud o la clave pueda acceder exactamente a un repositorio; de lo contrario, pásalo explícitamente.

macOS/Linux (Bash/Zsh)

# 
# Add to your shell profile for persistence:
echo 'export MAGUYVA_API_KEY="mgv_xxxx"' >> ~/.zshrc  # or ~/.bashrc
source ~/.zshrc  # reload

Windows (PowerShell)

# 
# Make it persist in your profile:
'$Env:MAGUYVA_API_KEY="mgv_xxxx"' | Out-File -Append $PROFILE
. $PROFILE

Reemplaza mgv_xxxx con tu clave de API real de app.maguyva.ai.

Configuración del cliente

#

Elige tu cliente MCP abajo para ver instrucciones de configuración específicas.

Nota de compatibilidad: Maguyva usa el estándar MCP. Cualquier cliente compatible con MCP puede conectarse al mismo servidor, incluso si todavía no hemos escrito una guía de configuración oficial para él.

Claude Code

Instala el plugin de Maguyva desde el marketplace de Claude Code:

Agrega el marketplace de Maguyva y luego instala el plugin (ejecuta cada comando dentro de Claude Code):

/plugin marketplace add maguyva/agent-plugins
/plugin install maguyva@maguyva

/plugin install abre los detalles del plugin, donde eliges el alcance de la instalación: solo tú (user), todas las personas que trabajan en este repositorio (project) o solo tú en este repositorio (local). Estos comandos dentro de la sesión no aceptan el flag --scope.

El plugin se autentica mediante la variable de entorno MAGUYVA_API_KEY. Configúrala en tu shell:

export MAGUYVA_API_KEY=mgv_xxxx

Se recomienda direnv (.envrc) por proyecto — las claves tienen alcance por repositorio, así que un valor por proyecto coincide con el acceso de cada uno. Un export global del shell funciona si una sola clave cubre todo tu trabajo.

Para un equipo, también puedes ejecutar la forma de shell de ambos comandos desde la raíz del repositorio, fuera de Claude Code:

claude plugin marketplace add maguyva/agent-plugins --scope project
claude plugin install maguyva@maguyva --scope project

El alcance project registra el plugin en el .claude/settings.json del repositorio, al que haces commit. Eso activa el plugin para tus compañeros, pero no lo descarga, así que cada compañero ejecuta el comando de instalación una vez.

Manual (.mcp.json) — avanzado
claude mcp add 
claude mcp add --transport http maguyva https://maguyva.tools/mcp --header 'Authorization: Bearer ${MAGUYVA_API_KEY}'
.mcp.json 
{
  "mcpServers": {
    "maguyva": {
      "type": "http",
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

Reemplaza mgv_xxxx con tu clave de API de app.maguyva.ai.

Lo que Maguyva le suma a Claude Code →

Documentación MCP de Claude Code →

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

Agrégalo a tu archivo de configuración de Claude Desktop:

claude_desktop_config.json 
{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "@maguyva/mcp"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

Reemplaza mgv_xxxx con tu clave de API de app.maguyva.ai.

claude_desktop_config.json solo inicia servidores locales, así que esta configuración usa el bridge @maguyva/mcp (requiere Node.js / npx). Claude Desktop también puede llegar a Maguyva como conector personalizado (Customize → Connectors) con un encabezado de solicitud authorization, pero los encabezados de solicitud están en beta para un número limitado de organizaciones.

Lo que Maguyva le suma a Claude Desktop →

Documentación MCP de Claude Desktop →

Cursor

macOS: ~/.cursor/mcp.json
Windows: %UserProfile%\.cursor\mcp.json
Linux: ~/.cursor/mcp.json

Agrégalo a .cursor/mcp.json en la raíz de tu proyecto:

.cursor/mcp.json 
{
  "mcpServers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MAGUYVA_API_KEY}"
      }
    }
  }
}

Esta configuración lee tu clave desde la variable de entorno MAGUYVA_API_KEY. Asígnale tu clave de API de app.maguyva.ai en el entorno desde el que se inicia tu cliente.

Lo que Maguyva le suma a Cursor →

Documentación MCP de Cursor →

VS Code / GitHub Copilot

Añádelo a .vscode/mcp.json en tu proyecto, o al mcp.json de tu perfil (ejecuta MCP: Open User Configuration):

.vscode/mcp.json 
{
  "servers": {
    "maguyva": {
      "type": "http",
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MAGUYVA_API_KEY}"
      }
    }
  }
}

Esta configuración lee tu clave desde la variable de entorno MAGUYVA_API_KEY. Asígnale tu clave de API de app.maguyva.ai en el entorno desde el que se inicia tu cliente.

Este es el formato de VS Code (clave servers). VS Code resuelve la referencia a MAGUYVA_API_KEY desde el entorno en el que arranca. Su flujo Add Server ahora prefiere el .mcp.json portable (clave mcpServers), que también lee GitHub Copilot CLI; ese archivo no admite las variables de entrada ni los archivos de entorno de VS Code.

Lo que Maguyva le suma a VS Code / GitHub Copilot →

Documentación MCP de VS Code / GitHub Copilot →

Devin Desktop (Windsurf)

macOS: ~/.config/devin/mcp_config.json
Windows: %APPDATA%\devin\mcp_config.json
Linux: ~/.config/devin/mcp_config.json

Windsurf ahora es Devin Desktop. Añádelo a su archivo de configuración de MCP:

mcp_config.json 
{
  "mcpServers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MAGUYVA_API_KEY}"
      }
    }
  }
}

Esta configuración lee tu clave desde la variable de entorno MAGUYVA_API_KEY. Asígnale tu clave de API de app.maguyva.ai en el entorno desde el que se inicia tu cliente.

Devin Local, el agente predeterminado, lee este archivo desde la versión 3.6; las versiones anteriores guardaban los servidores en el archivo de configuración principal y los mueven aquí al arrancar. El antiguo agente Cascade, con el que no se inician las conversaciones nuevas, lee el mismo archivo. Devin Desktop resuelve la referencia a MAGUYVA_API_KEY desde el entorno en el que arranca.

Lo que Maguyva le suma a Devin Desktop (Windsurf) →

Documentación MCP de Devin Desktop (Windsurf) →

Codex

macOS: ~/.codex/config.toml
Windows: %UserProfile%\.codex\config.toml
Linux: ~/.codex/config.toml

Agrégalo a tu configuración de Codex CLI (~/.codex/config.toml):

.codex/config.toml 
[mcp_servers.maguyva]
url = "https://maguyva.tools/mcp"
bearer_token_env_var = "MAGUYVA_API_KEY"

Esta configuración lee tu clave desde la variable de entorno MAGUYVA_API_KEY. Asígnale tu clave de API de app.maguyva.ai en el entorno desde el que se inicia tu cliente.

Lo que Maguyva le suma a Codex →

Documentación MCP de Codex →

GitHub Copilot CLI

Agrégalo a ~/.copilot/mcp-config.json:

~/.copilot/mcp-config.json 
{
  "mcpServers": {
    "maguyva": {
      "type": "http",
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      }
    }
  }
}
copilot mcp add 
copilot mcp add --transport http --header "Authorization: Bearer mgv_xxxx" maguyva https://maguyva.tools/mcp

Reemplaza mgv_xxxx con tu clave de API de app.maguyva.ai.

Lo que Maguyva le suma a GitHub Copilot CLI →

Documentación MCP de GitHub Copilot CLI →

Gemini CLI

macOS: ~/.gemini/settings.json
Windows: %UserProfile%\.gemini\settings.json
Linux: ~/.gemini/settings.json

Agrégalo a tu configuración de Gemini CLI (~/.gemini/settings.json):

settings.json 
{
  "mcpServers": {
    "maguyva": {
      "httpUrl": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

Esta configuración lee tu clave desde la variable de entorno MAGUYVA_API_KEY. Asígnale tu clave de API de app.maguyva.ai en el entorno desde el que se inicia tu cliente.

Lo que Maguyva le suma a Gemini CLI →

Documentación MCP de Gemini CLI →

Cline

macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
Windows: %AppData%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Agrégalo a tu configuración MCP de Cline:

cline_mcp_settings.json 
{
  "mcpServers": {
    "maguyva": {
      "type": "streamableHttp",
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Reemplaza mgv_xxxx con tu clave de API de app.maguyva.ai.

Lo que Maguyva le suma a Cline →

Documentación MCP de Cline →

Goose

macOS: ~/.config/goose/config.yaml
Windows: %APPDATA%\Block\goose\config\config.yaml
Linux: ~/.config/goose/config.yaml

Agrégalo a tu configuración de Goose:

config.yaml 
extensions:
  maguyva:
    name: maguyva
    type: streamable_http
    uri: https://maguyva.tools/mcp
    enabled: true
    headers:
      Authorization: Bearer mgv_xxxx
    timeout: 300

Reemplaza mgv_xxxx con tu clave de API de app.maguyva.ai.

Lo que Maguyva le suma a Goose →

Documentación MCP de Goose →

LM Studio

En LM Studio, abre la pestaña Program en la barra lateral derecha, elige Install → Edit mcp.json y añade:

mcp.json 
{
  "mcpServers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      }
    }
  }
}

Reemplaza mgv_xxxx con tu clave de API de app.maguyva.ai.

Documentación MCP de LM Studio →

Continue

Guárdalo como .continue/mcpServers/maguyva.yaml en tu espacio de trabajo (o añade la entrada mcpServers a ~/.continue/config.yaml) y define MAGUYVA_API_KEY en ~/.continue/.env:

.continue/mcpServers/maguyva.yaml 
name: Maguyva
version: 0.0.1
schema: v1
mcpServers:
  - name: maguyva
    type: streamable-http
    url: https://maguyva.tools/mcp
    requestOptions:
      headers:
        Authorization: Bearer ${{ secrets.MAGUYVA_API_KEY }}

Esta configuración lee tu clave desde la variable de entorno MAGUYVA_API_KEY. Asígnale tu clave de API de app.maguyva.ai en el entorno desde el que se inicia tu cliente.

Continue solo usa servidores MCP en modo agente. Busca el secreto en ~/.continue/.env, luego en .continue/.env y .env del espacio de trabajo y, por último, en el entorno del proceso.

Lo que Maguyva le suma a Continue →

Documentación MCP de Continue →

Kiro CLI (Amazon Q Developer CLI)

macOS: ~/.kiro/settings/mcp.json
Windows: %USERPROFILE%\.kiro\settings\mcp.json
Linux: ~/.kiro/settings/mcp.json

Añádelo a la configuración MCP de Kiro CLI (~/.kiro/settings/mcp.json, o .kiro/settings/mcp.json en un proyecto):

mcp.json 
{
  "mcpServers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      }
    }
  }
}

Reemplaza mgv_xxxx con tu clave de API de app.maguyva.ai.

Kiro CLI reemplazó a Amazon Q Developer CLI. Al instalarlo, copia una sola vez tus servidores de ~/.aws/amazonq/mcp.json a ~/.kiro/settings/mcp.json, y el .kiro/settings/mcp.json de un proyecto tiene prioridad sobre el archivo de usuario.

Documentación MCP de Kiro CLI (Amazon Q Developer CLI) →

PyCharm

Pégalo en Settings | Tools | AI Assistant | Model Context Protocol (MCP) → Add, como configuración JSON: 

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "@maguyva/mcp"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

Reemplaza mgv_xxxx con tu clave de API de app.maguyva.ai.

Esta configuración utiliza el bridge @maguyva/mcp (requiere Node.js / npx). No se ha verificado una configuración de conexión remota nativa para este cliente en esta guía; esto no significa que el cliente carezca de soporte nativo para conexiones remotas. Maguyva se ejecuta completamente en remoto — solo el bridge se ejecuta localmente.

Documentación MCP de PyCharm →

Zed

macOS: ~/.config/zed/settings.json
Windows: %AppData%\Zed\settings.json
Linux: ~/.config/zed/settings.json

Agrégalo a tu configuración de Zed (~/.config/zed/settings.json):

settings.json 
{
  "context_servers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      }
    }
  }
}

Reemplaza mgv_xxxx con tu clave de API de app.maguyva.ai.

Lo que Maguyva le suma a Zed →

Documentación MCP de Zed →

Trae

Activa Enable Project MCP en Settings → MCP y luego añádelo a .trae/mcp.json en la raíz del proyecto:

.trae/mcp.json 
{
  "mcpServers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      }
    }
  }
}

Reemplaza mgv_xxxx con tu clave de API de app.maguyva.ai.

Documentación MCP de Trae →

OpenCode

Agrégalo a opencode.json en la raíz de tu proyecto:

opencode.json 
{
  "mcp": {
    "maguyva": {
      "type": "remote",
      "url": "https://maguyva.tools/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:MAGUYVA_API_KEY}"
      }
    }
  }
}

Esta configuración lee tu clave desde la variable de entorno MAGUYVA_API_KEY. Asígnale tu clave de API de app.maguyva.ai en el entorno desde el que se inicia tu cliente.

Lo que Maguyva le suma a OpenCode →

Documentación MCP de OpenCode →

BoltAI

macOS: ~/.boltai/mcp.json

Agrégalo a tu configuración MCP de BoltAI:

mcp.json 
{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "@maguyva/mcp"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

Reemplaza mgv_xxxx con tu clave de API de app.maguyva.ai.

Esta configuración utiliza el bridge @maguyva/mcp (requiere Node.js / npx). No se ha verificado una configuración de conexión remota nativa para este cliente en esta guía; esto no significa que el cliente carezca de soporte nativo para conexiones remotas. Maguyva se ejecuta completamente en remoto — solo el bridge se ejecuta localmente.

Documentación MCP de BoltAI →

LibreChat

Añádelo a librechat.yaml y define MAGUYVA_API_KEY en el entorno del servidor de LibreChat:

librechat.yaml 
mcpServers:
  maguyva:
    type: streamable-http
    url: https://maguyva.tools/mcp
    headers:
      Authorization: Bearer ${MAGUYVA_API_KEY}
    requiresOAuth: false

Esta configuración lee tu clave desde la variable de entorno MAGUYVA_API_KEY. Asígnale tu clave de API de app.maguyva.ai en el entorno desde el que se inicia tu cliente.

Documentación MCP de LibreChat →

Antigravity

macOS: ~/.gemini/config/mcp_config.json
Windows: %UserProfile%\.gemini\config\mcp_config.json
Linux: ~/.gemini/config/mcp_config.json

Agrégalo a tu configuración MCP de Antigravity:

mcp_config.json 
{
  "mcpServers": {
    "maguyva": {
      "serverUrl": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      }
    }
  }
}

Reemplaza mgv_xxxx con tu clave de API de app.maguyva.ai.

Lo que Maguyva le suma a Antigravity →

Documentación MCP de Antigravity →

Claude Cowork

Claude Cowork no carga servidores de claude_desktop_config.json; llega a los servidores remotos como conectores personalizados. En Customize → Connectors, añade un conector personalizado con la URL https://maguyva.tools/mcp, elige No sign-in y añade un encabezado de solicitud authorization cuyo valor sea Bearer seguido de tu clave de API. Los encabezados de solicitud están en beta para un número limitado de organizaciones; si el diálogo no tiene la sección Request headers, Cowork todavía no puede autenticarse en Maguyva. Ver documentación →

ChatGPT

ChatGPT admite servidores MCP remotos en los planes Business, Enterprise y Edu a través de Settings → Apps → Create. Se requiere un endpoint HTTPS remoto — ChatGPT no admite servidores stdio locales. Consulta la guía de MCP de OpenAI para la configuración. Ver documentación →

Warp

Añádelo a ~/.warp/.mcp.json (o a .warp/.mcp.json en un proyecto), o pégalo en Settings → Agents → MCP servers → + Add:

~/.warp/.mcp.json 
{
  "mcpServers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      }
    }
  }
}

Reemplaza mgv_xxxx con tu clave de API de app.maguyva.ai.

Lo que Maguyva le suma a Warp →

Documentación MCP de Warp →

Maguyva usa el estándar MCP. Cualquier cliente que soporte el protocolo puede conectarse, incluso si no hay una guía propia arriba. 23 clientes documentados, y se agregan más con regularidad.

Valida tu configuración

#

Después de conectar, prueba a hacerle a tu agente algunas preguntas:

  • "¿Qué repositorios tengo conectados?" — verifica que la conexión funcione
  • "¿Cómo se maneja la autenticación en este código?" — pone a prueba la búsqueda semántica
  • "Encuentra todas las funciones que llaman a la base de datos" — pone a prueba la búsqueda de dependencias
  • "¿De qué depende la clase UserService?" — pone a prueba la búsqueda de símbolos

Deberías ver resultados con rutas de archivo y números de línea de tu repositorio conectado. Si no es así, revisa la sección de troubleshooting section más abajo.

Formato del repositorio

#

Al especificar repositorios:

  • Con rama: "owner/repo:branch" (e.g., "owner/repository:develop")
  • Rama predeterminada: "owner/repo"

Consejo: usa repository_context(action="info", repository="...") para comprobar la resolución del repositorio. Una selección explícita que sustituye al repositorio predeterminado solo afecta a la llamada actual.

Solución de problemas

#

Problemas con la clave de API

#
  • Verifica que tu clave empiece con el prefijo mgv_
  • Comprueba que la clave esté correctamente configurada en tu entorno
  • Asegúrate de que la clave no haya expirado

Repositorio no encontrado

#
  • Verifica que el repositorio esté conectado en app.maguyva.ai
  • Comprueba que el formato owner/repo sea correcto
  • Asegúrate de tener acceso al repositorio

Problemas de conexión MCP

#
  • Si tu cliente utiliza el bridge @maguyva/mcp, comprueba que npx esté disponible en tu PATH
  • Comprueba que tu token de API sea válido y no haya expirado
  • Prueba la conectividad con https://maguyva.tools/mcp
  • Revisa la sintaxis de configuración MCP de tu cliente

Próximos pasos

#

Relacionado

Sigue leyendo