Gosar MCP Server

An MCP server that lets Claude call the Gosar API on a user's behalf, authenticated via Gosar's OAuth 2.0 + PKCE flow.

It acts as a bridge:

• To Claude (the MCP client), it behaves like a full OAuth authorization server — handling dynamic client registration and issuing its own short-lived tokens.
• To Gosar, it is the single, pre-registered OAuth client (public, PKCE-only) that performs the real Authorization Code + PKCE exchange described in Gosar's integration guide.

Prerequisites

• Python 3.11+
• A Gosar OAuth client registered with the Gosar team (see "What we need from you" in the integration guide) — you need a client_id and an approved redirect URI.
• ngrok (or similar) if you want to test against the real Gosar API — Gosar's redirect URI must be HTTPS and match exactly, and Claude also needs an HTTPS URL to connect a remote MCP server to.

1. Install dependencies

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

2. Configure .env

Copy the values you have into .env at the project root:

# 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=

Generate a signing key (Gosar is a public client with no secret, so this can't be derived automatically — it's required):

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

Paste the output into JWT_SIGNING_KEY. Keep it the same across restarts, or every connected user gets logged out.

3. Expose your server over HTTPS (for real Gosar testing)

Claude and Gosar both require HTTPS. In a separate terminal:

ngrok http 8000

Copy the https://...ngrok-free.app URL into MCP_PUBLIC_BASE_URL in .env, and send {MCP_PUBLIC_BASE_URL}/gosar/callback to the Gosar team as your registered redirect URI.

4. Run the server

source .venv/bin/activate
python main.py

You should see:

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

Auto-reload on code changes

python main.py does not reload — mcp.run() blocks and owns its own uvicorn process, which can't be handed to a file-watching reloader. For development, run the ASGI app in gosar_mcp/asgi.py under uvicorn directly instead:

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

• --reload restarts the worker process whenever a .py file changes.
• --reload-include ".env" also restarts it when you edit .env (uvicorn only watches Python files by default, and env vars are only read once at process startup, so without this flag a .env edit needs a manual restart).
• Keep the port in sync with whatever your ngrok tunnel points at.

5. Sanity-check the OAuth wiring

With the server running, confirm discovery metadata is served:

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

You should see applications.read/applications.write in scopes_supported and S256 as the only PKCE method.

6. Connect it to Claude

In Claude's connector settings, add a remote MCP server pointing at:

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

Claude will register itself as an OAuth client against this server, redirect the user through consent, then through Gosar's real Google sign-in + consent screen, and land back here with an active connection. Ask Claude to call the whoami tool to confirm it's authenticated as the expected Gosar account.

Notes

• Token storage (client registrations + encrypted upstream Gosar tokens) defaults to an OS-appropriate encrypted file store on disk — no extra setup needed for local dev. See gosar_mcp/auth.py for where to point this at a different backend in production.
• gosar_mcp/tools.py's /applications endpoint paths are placeholders — the integration guide only specifies the OAuth layer, not the Applications REST API shape. Confirm the real paths/payloads with the Gosar team and adjust there.