Gnosari Documentation

Appearance

Connecting Claude Desktop and ChatGPT via OAuth ​

This guide explains how to connect Claude Desktop or ChatGPT to Gnosari MCP Server using OAuth 2.1 with PKCE. OAuth is the recommended authentication method for interactive clients — no API key is needed.

Prerequisites ​

  • Gnosari account at gnosari.com
  • Claude Desktop (any recent version) or ChatGPT with MCP support
  • uvx installed (for Claude Desktop via PyPI package)

How OAuth Works with Gnosari MCP ​

Gnosari MCP Server implements OAuth 2.1 with PKCE via the MCP authorization framework. The key point is that the entire OAuth flow is handled automatically by the client — you configure the MCP server URL and the client takes care of the rest.

Flow summary:

1. Client connects to https://mcp.gnosari.com/mcp (no token)
2. MCP → 401 + pointer to OAuth metadata
3. Client fetches OAuth server details from api.gnosari.com
4. Client registers itself (Dynamic Client Registration — automatic)
5. Browser opens https://gnosari.com/auth/authorize (a full Gnosari login page with both password and Google login options)
6. Client stores the JWT and uses it for all subsequent requests
7. Token is refreshed automatically before expiry

Steps 2–6 happen once. After that, the client reuses the stored token silently.

Claude Desktop Setup ​

Step 1: Install the MCP server package ​

bash
uvx install gnosari-mcp-server

Or use uvx directly without pre-installing (it fetches on first run).

Step 2: Edit Claude Desktop configuration ​

Open the configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

Add the Gnosari MCP server entry:

json
{
  "mcpServers": {
    "gnosari-manager": {
      "command": "uvx",
      "args": ["gnosari-mcp-server"],
      "env": {
        "GNOSARI_API_URL": "https://api.gnosari.com"
      }
    }
  }
}

No API key in the config. OAuth handles authentication — GNOSARI_API_KEY is not needed.

Step 3: Restart Claude Desktop ​

Close and reopen Claude Desktop completely (not just the window — quit the application).

Step 4: Complete the OAuth login ​

On first connection, Claude Desktop will open a browser window to gnosari.com/auth/authorize. This happens automatically when you start a conversation that uses Gnosari tools.

What you will see:

  1. Gnosari authorization page — choose your login method:
    • Option A (Password): Enter your email and password
    • Option B (Google): Click Login with Google, complete Google authentication, then return to the authorization page
  2. Consent screen — review the permissions and click Allow
  3. Browser closes and returns control to Claude Desktop
  4. Claude Desktop is now authenticated and stores the token

Note: Both login paths lead to the same consent screen. The method you choose is your preference — MCP access is identical either way.

Subsequent connections reuse the stored token silently. No browser window appears again until the refresh token expires (30 days by default).

ChatGPT Setup ​

ChatGPT's MCP integration follows the same OAuth flow. Refer to OpenAI's documentation for the exact configuration UI, but the MCP server URL to provide is:

https://mcp.gnosari.com/mcp

ChatGPT will handle Dynamic Client Registration and the OAuth flow automatically when you add the server.

What to Expect ​

First connection ​

  • Browser window opens for Gnosari login (automatic)
  • One-time consent screen appears
  • After approval, the client stores an access token and a 30-day refresh token

Subsequent connections ​

  • No browser window — token is reused silently
  • Token is refreshed automatically before it expires
  • If the refresh token expires (after 30 days of inactivity), you will be prompted to log in again

Token scope ​

The OAuth token grants access to the same resources as your Gnosari account. The consent screen lists the exact permissions requested.

Troubleshooting ​

Browser window does not open ​

Cause: Claude Desktop may not have permission to open the browser, or the configuration file has a syntax error.

Fix:

  1. Validate the JSON in claude_desktop_config.json (use jsonlint.com)
  2. Restart Claude Desktop
  3. Check Claude Desktop logs for errors

"Authentication failed" or "Invalid token" ​

Cause: The stored token may be corrupted, or the OAuth server returned an error during the flow.

Fix:

  1. Clear stored OAuth tokens in Claude Desktop settings (or delete the token cache file)
  2. Restart Claude Desktop and complete the OAuth flow again

Login page shows "Invalid client" ​

Cause: The Dynamic Client Registration step failed, or the client ID is no longer valid.

Fix:

  1. Remove and re-add the MCP server in Claude Desktop
  2. The client will re-register automatically on the next connection

Cause: The token storage is not persisting between sessions (permission issue or sandboxed environment).

Fix: Ensure Claude Desktop has write access to its data directory:

  • macOS: ~/Library/Application Support/Claude/
  • Windows: %APPDATA%\Claude\

Clicked "Login with Google" but nothing happens or see an error ​

Cause: Google OAuth credentials are not configured, or there is a redirect URI mismatch in Google Cloud Console.

Fix:

  1. Try the password login option instead as an immediate workaround
  2. If you are the Gnosari administrator, verify NUXT_PUBLIC_GOOGLE_CLIENT_ID is set in the UI environment
  3. Confirm that https://gnosari.com/auth/google/callback is listed as an authorized redirect URI in Google Cloud Console

Google login shows "No Gnosari account found for this Google email" ​

Cause: The Google account's email address does not match any existing Gnosari account.

Fix:

  1. Use password login with your Gnosari account email
  2. Or sign up at gnosari.com using the same email address as your Google account

"Connection refused" or "Cannot reach MCP server" ​

Cause: Network issue or the MCP server URL is incorrect.

Fix:

bash
curl https://mcp.gnosari.com/.well-known/oauth-protected-resource

Expected response: JSON with resource and authorization_servers fields. If this fails, check your network connection.

Backward Compatibility ​

OAuth is additive — it does not replace API key or JWT token authentication. Existing configurations using GNOSARI_API_KEY or GNOSARI_USER_TOKEN continue to work without modification.

The authentication precedence is:

  1. Authorization: Bearer <JWT> (OAuth) — tried first; falls through to step 2 if JWT validation fails
  2. Authorization: Bearer gak_* (DB API key) — Bearer token validated against account_api_key table
  3. Gnosari-Api-Key header (API key) — only checked when no Authorization: Bearer header is present
  4. Gnosari-User-Token header (JWT token)

If you have an existing API key configuration and want to switch to OAuth, simply remove GNOSARI_API_KEY from the env section in claude_desktop_config.json and restart Claude Desktop.