Gosar MCP Server

Un servidor MCP que permite a Claude llamar a la API de Gosar en nombre de un usuario, autenticado mediante el flujo OAuth 2.0 + PKCE de Gosar.

Actúa como puente:

• Para Claude (el cliente MCP), se comporta como un servidor de autorización OAuth completo: gestiona el registro dinámico de clientes y emite sus propios tokens de corta duración.

• Para Gosar, es el único cliente OAuth pre-registrado (público, solo PKCE) que realiza el intercambio real de Código de Autorización + PKCE descrito en la guía de integración de Gosar.

Requisitos previos

• Python 3.11+

• Un cliente OAuth de Gosar registrado con el equipo de Gosar (consulta "Qué necesitamos de ti" en la guía de integración): necesitas un client_id y una URI de redirección aprobada.

• ngrok (o similar) si quieres probar contra la API real de Gosar: la URI de redirección de Gosar debe ser HTTPS y coincidir exactamente, y Claude también necesita una URL HTTPS para conectar un servidor MCP remoto.

Related MCP server: lighthouse-mcp-oauth

1. Instalar dependencias

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. Configurar .env

Copia los valores que tengas en .env en la raíz del proyecto:

# Real values from the Gosar team
GOSAR_API_BASE_URL=https://api.gosar.example
GOSAR_CLIENT_ID=your-registered-client-id
GOSAR_SCOPES=applications.read applications.write

# Your server's own public HTTPS URL (e.g. your ngrok URL). Gosar's registered
# redirect_uri must be exactly this + GOSAR_REDIRECT_PATH.
MCP_PUBLIC_BASE_URL=https://your-tunnel.ngrok-free.app
GOSAR_REDIRECT_PATH=/gosar/callback

MCP_HOST=0.0.0.0
MCP_PORT=8000

# Generate once and keep stable — see below
JWT_SIGNING_KEY=

Genera una clave de firma (Gosar es un cliente público sin secreto, por lo que no se puede derivar automáticamente; es obligatorio):

python -c "import secrets; print(secrets.token_urlsafe(32))"

Pega la salida en JWT_SIGNING_KEY. Mantenla igual entre reinicios, o todos los usuarios conectados se desconectarán.

3. Exponer tu servidor a través de HTTPS (para pruebas reales con Gosar)

Tanto Claude como Gosar requieren HTTPS. En una terminal separada:

ngrok http 8000

Copia la URL https://...ngrok-free.app en MCP_PUBLIC_BASE_URL en .env, y envía {MCP_PUBLIC_BASE_URL}/gosar/callback al equipo de Gosar como tu URI de redirección registrada.

4. Ejecutar el servidor

source .venv/bin/activate
python main.py

Deberías ver:

Starting MCP server 'Gosar' with transport 'http' on http://0.0.0.0:8000/mcp
Uvicorn running on http://0.0.0.0:8000

Recarga automática en cambios de código

python main.py no se recarga: mcp.run() bloquea y posee su propio proceso de uvicorn, que no se puede entregar a un recargador que vigile archivos. Para desarrollo, ejecuta la aplicación ASGI en gosar_mcp/asgi.py directamente bajo uvicorn:

uvicorn gosar_mcp.asgi:app --reload --reload-include ".env" --host 0.0.0.0 --port 8000

• --reload reinicia el proceso del worker cada vez que cambia un archivo .py.

• --reload-include ".env" también lo reinicia cuando editas .env (uvicorn solo vigila archivos Python por defecto, y las variables de entorno solo se leen una vez al iniciar el proceso, por lo que sin esta bandera, una edición de .env requiere un reinicio manual).

• Mantén el puerto sincronizado con lo que apunte tu túnel de ngrok.

5. Verificar la configuración de OAuth

Con el servidor en ejecución, confirma que se sirven los metadatos de descubrimiento:

curl -s http://127.0.0.1:8000/.well-known/oauth-authorization-server | python3 -m json.tool

Deberías ver applications.read/applications.write en scopes_supported y S256 como único método PKCE.

6. Conectarlo a Claude

En la configuración del conector de Claude, añade un servidor MCP remoto que apunte a:

https://your-tunnel.ngrok-free.app/mcp

Claude se registrará como cliente OAuth contra este servidor, redirigirá al usuario a través del consentimiento, luego a la pantalla real de inicio de sesión de Google + consentimiento de Gosar, y volverá aquí con una conexión activa. Pide a Claude que llame a la herramienta whoami para confirmar que está autenticado como la cuenta de Gosar esperada.

Notas

• El almacenamiento de tokens (registros de clientes + tokens de Gosar cifrados) por defecto es un almacén de archivos cifrado apropiado para el sistema operativo en disco: no se necesita configuración adicional para el desarrollo local. Consulta gosar_mcp/auth.py para saber dónde apuntar a un backend diferente en producción.

• Las rutas de endpoint /applications de gosar_mcp/tools.py son marcadores de posición: la guía de integración solo especifica la capa OAuth, no la forma de la API REST de Applications. Confirma las rutas/cargas útiles reales con el equipo de Gosar y ajústalas allí.