Connecting Claude to Gong via MCP:

A Field Guide Through the Undocumented Gaps

The Idea It started with a simple question: what if your AI assistant could tap directly into Gong’s revenue intelligence — without you having to copy-paste call summaries, manually pull deal notes, or context-switch between tools?

Gong recently launched a Model Context Protocol (MCP) server in Beta. MCP is an open standard that lets AI systems like Claude connect to external data sources and tools in a structured, secure way. In theory, connecting Claude Desktop to the Gong MCP server would mean you could ask Claude things like:

“What objections has Acme raised in the last 30 days?” “What are the blockers on the Salesforce deal?” “Generate an executive brief for the TechCorp account.”

…and Claude would reach into Gong, analyze actual call and messaging data, and respond with synthesized, AI-powered insights — right inside the chat window.

That’s the promise. Getting there required navigating a series of undocumented gaps, misleading error messages, and some good old-fashioned debugging. This guide captures every step — including the wrong turns — so you don’t have to repeat them.

───────────────────────────────────────────────

What You’re Building At the end of this guide you will have:

• A Gong OAuth integration with MCP scope enabled
• A working OAuth access token (valid 24 hours, refreshable)
• Claude Desktop configured to connect to the Gong MCP server via mcp remote
• Access to three Gong AI tools directly inside Claude Desktop chat

Architecture at a Glance

Claude Desktop     
     └── mcp-remote (npx bridge)            
          └── Gong MCP Server  (https://api.gong.io/mcp/message)                   
                 └── Gong AI Engine  (ask_account, ask_deal, generate_brief)

Authentication flows through Gong OAuth 2.0. Claude Desktop uses the Bearer access token to authenticate every MCP request.

Prerequisites

• Gong Technical Administrator access
• Gong MCP Beta enabled on your organization (requires feature flag + Gen AI Beta + Gong Credits Beta)
• Claude Desktop installed (claude.ai/download)
• Node.js installed (verify: npx — version)
• Python 3 installed

⚠️ Watch out: The MCP Beta is rolling out to selected customers alongside the Gong Credits Beta. If you don’t see the MCP scope option in your integration settings, your org may not yet be enrolled.

Step 1: Create a Dedicated MCP Integration Where: Gong Admin Center → Ecosystem → API → Integrations tab

Gong’s documentation is clear on one point: do not reuse an existing integration for MCP. Create a new, dedicated one. This prevents the MCP connection from inheriting broad access permissions set up for other purposes.

Create the Integration

• Log into Gong as a Technical Administrator
• Navigate to: Admin Center → Ecosystem → API → Integrations tab
• Click “Create” to start a new integration

Fill in the Fields

• mcp scope checkbox — check this. Without it, every MCP request will be rejected.
• Redirect URI — required. See below.
• Authorization scopes — not enforced during Beta. Can be skipped.
• Other fields (support URL, etc.) — placeholder values are fine.

Setting Up the Redirect URI The Redirect URI is where Gong sends the authorization code after your admin approves the app. Since we’re doing this manually (not as part of a deployed web app), we use a localhost URI and catch the code with a simple Python HTTP server.

Register this URI in your Gong integration:

http://localhost:8080/callback

Create a file called callback_listener.py:

from http.server import HTTPServer, BaseHTTPRequestHandler
from urllib.parse import urlparse, parse_qs

class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        params = parse_qs(urlparse(self.path).query)
        code = params.get('code', ['Not found'])[0]
        print('\n✓ Authorization code:', code, '\n')
        self.send_response(200)
        self.end_headers()
        self.wfile.write(b'Done! Authorization code captured.')
    def log_message(self, *args): pass

print('Listening on http://localhost:8080 ...')
HTTPServer(('localhost', 8080), Handler).handle_request()

Run it with:

python3 callback_listener.py

💡 Tip: Don’t use python3 -c “…” for multiline scripts — indentation errors will occur. Always save to a .py file and run it directly.

Result After saving the integration, Gong provides:

• Client ID — a short alphanumeric string identifying your OAuth app
• Client Secret — keep this secure, never commit to version control

Step 2: Obtain an OAuth Access Token “This is where the documentation ends and the debugging begins.” — Every developer who has ever done OAuth integration

The access token is what authenticates every MCP request. You get it by exchanging a short-lived authorization code through a three-part OAuth 2.0 flow. The authorization code is valid for 10 minutes, so have everything ready before starting.

Part A — Start the Callback Listener In a terminal window, start the listener so it’s ready to catch the redirect:

python3 callback_listener.py

You should see: Listening on http://localhost:8080 …

Part B — Admin Authorizes the App Have your Technical Administrator (logged into Gong) open this URL in their browser. Replace YOUR_REGION and YOUR_CLIENT_ID with your values.

https://YOUR_REGION.app.gong.io/oauth2/authorize?response_type=code&client
_id=YOUR_CLIENT_ID&redirect_uri=http://localhost:8080/callback&scope=mcp

⚠️ Watch out: Use scope=mcp — not scope=api. Using the wrong scope results in a token that the MCP server rejects.

After the admin approves, Gong redirects to your callback. The terminal will print the authorization code. Copy it immediately.

Part C — Exchange the Code for a Token Create a file called get_token.py. Fill in your Client ID, Client Secret, and the authorization code you just captured.

import http.client, urllib.parse, base64, json, ssl

CLIENT_ID = "YOUR_CLIENT_ID"
CLIENT_SECRET = "YOUR_CLIENT_SECRET"
AUTHORIZATION_CODE = "YOUR_AUTHORIZATION_CODE"
REDIRECT_URI = "http://localhost:8080/callback"

credentials = base64.b64encode(
    f"{CLIENT_ID}:{CLIENT_SECRET}".encode()
).decode()

body = urllib.parse.urlencode({
    "grant_type": "authorization_code",
    "client_id": CLIENT_ID,
    "code": AUTHORIZATION_CODE,
    "redirect_uri": REDIRECT_URI,
})

headers = {
    "Authorization": f"Basic {credentials}",
    "Content-Type": "application/x-www-form-urlencoded",
    "Content-Length": str(len(body)),
    "Accept": "application/json",
}

ctx = ssl.create_default_context()
conn = http.client.HTTPSConnection("app.gong.io", context=ctx)
conn.request("POST", "/oauth2/generate-customer-token",
             body=body, headers=headers)
r = conn.getresponse()
result = json.loads(r.read())
print("✓ Access token:", result.get("access_token"))
print("✓ Refresh token:", result.get("refresh_token"))
print("✓ Expires in:", result.get("expires_in"), "seconds")
conn.close()

Run it:

python3 get_token.py

The Correct Token Endpoint (Hard Won) This was the hardest part to figure out. Here is the definitive answer so you don’t spend hours debugging it:

✅ Correct: https://app.gong.io/oauth2/generate-customer-token ❌ Wrong: https://api.gong.io/v2/oauth2/generate-customer-token (404 Not Found) ❌ Wrong: https://YOUR_REGION.app.gong.io/oauth2/token (302 redirect to login page — browser sessions only)

Authentication for the token endpoint: ✅ Basic Auth using OAuth Client ID + Client Secret ❌ NOT the Gong API Access Key + Secret Key (those are separate credentials for direct API access only)

💡 Tip: Use Python’s http.client directly rather than urllib.request for this call. urllib can interfere with Authorization headers in some configurations.

Token Details access_token — Bearer token used in all MCP requests. Valid for 24 hours. refresh_token — use this to get a new access token without re-authorizing. expires_in: 86400–24 hours in seconds.

Refreshing the Token When the token expires, POST to the same endpoint with:

grant_type=refresh_token
refresh_token=YOUR_REFRESH_TOKEN
client_id=YOUR_CLIENT_ID

No admin re-authorization required.

Step 3: Configure Claude Desktop Claude Desktop is the MCP client. It doesn’t support direct URL connections to MCP servers — it needs mcp-remote as a bridge for HTTP transport.

Prerequisites

• Claude Desktop installed (claude.ai/download)
• Node.js / npx installed. Verify: npx — version

Locate the Config File

~/Library/Application Support/Claude/claude_desktop_config.json

Add the MCP Server Add the mcpServers section to your existing config. Replace YOUR_ACCESS_TOKEN with the token from Step 2.

{
  "preferences": {
    ... your existing preferences ...
  },
  "mcpServers": {
    "gong": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.gong.io/mcp/message",
        "--header",
        "Authorization:Bearer YOUR_ACCESS_TOKEN"
      ]
    }
  }
}

⚠️ Watch out: Claude Desktop requires a command-based format. A direct “url” field causes a “mcpServers.gong.command Required” error on startup and reverts your config.

⚠️ Watch out: Write Authorization:Bearer with no space after the colon when passed as a mcp-remote argument.

Restart and Verify

• Save the config file
• Fully quit and relaunch Claude Desktop
• Look for the hammer icon (🔨) in the chat input — this confirms the Gong MCP tools are connected

Step 4: Using Gong Tools in Claude Desktop No special syntax required. Just ask Claude naturally — it will invoke the right Gong tool automatically and show you a tool call notification before responding.

The Three Tools ask_account Answer a targeted question about a CRM account based on Gong activity. “What are the top objections raised by Acme in the last 30 days?” “Which competitors has Acme mentioned most often?” “What risks should I be aware of for the Acme account?”

ask_deal Answer a targeted question about a CRM deal or opportunity. “What are the main blockers preventing the Acme deal from closing?” “What next steps were agreed upon in recent Acme deal calls?”

generate_brief Generate a structured multi-category summary for an account, deal, or contact. “Generate an account brief for Acme covering the last 30 days.” “Create an executive briefing for the TechCorp deal.”

What You’ll Need Workspace ID — Gong Admin Center → Company → Workspaces (check the URL params) CRM Account or Deal ID — from your CRM (e.g. Salesforce account/opportunity ID) Date range — fromDateTime and toDateTime in ISO 8601 format

💡 Tip: Include these in your prompt and Claude will pass them directly to the tool. Example: “My Gong workspace ID is XXXXX, Salesforce account ID is YYYYY — what objections has Acme raised in the last 30 days?”

Lessons Learned: The Wrong Turns If you hit errors along the way, this section will save you hours.

❌ “Missing mandatory header Authorization” (from api.gong.io) This is a misleading error. The header was being sent. The real issue: api.gong.io/v2/oauth2/generate-customer-token is the wrong endpoint entirely. Use app.gong.io/oauth2/generate-customer-token instead.

❌ 302 redirect to /welcome/sign-in (from app.gong.io/oauth2/token) The /oauth2/token path on the app domain requires an active browser session. It is not a machine-accessible OAuth token endpoint.

❌ 404 Not Found (from api.gong.io/v2/oauth2/…) The /v2/ prefix does not exist for the OAuth token endpoint. The path is simply /oauth2/generate-customer-token on app.gong.io.

❌ API Access Keys returning 404 on token endpoint Gong API Access Keys (from Admin Center → API → API Keys) are for direct API access only. The OAuth token endpoint requires the OAuth Client ID + Client Secret.

❌ “mcpServers.gong.command Required” (Claude Desktop) Claude Desktop does not support a direct URL-based MCP config. Use npx mcp-remote as the command bridge.

❌ Config reverts to previous version (Claude Desktop) This happens when the JSON is invalid or fails schema validation. Always validate your JSON before saving and restarting.

❌ scope=api produces a token the MCP server rejects The authorization URL must include scope=mcp. Without it, the MCP server will reject all requests.

Quick Reference Key URLs

• Authorization endpoint: https://YOUR_REGION.app.gong.io/oauth2/authorize
• Token endpoint: https://app.gong.io/oauth2/generate-customer-token
• MCP Server (Beta): https://api.gong.io/mcp/message
• OAuth documentation: https://help.gong.io/docs/create-an-app-for-gong

Authorization URL Template

https://YOUR_REGION.app.gong.io/oauth2/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=http://localhost:8080/callback
  &scope=mcp

Token Endpoint — Request Summary

POST https://app.gong.io/oauth2/generate-customer-token
Authorization: Basic base64(CLIENT_ID:CLIENT_SECRET)
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=YOUR_CLIENT_ID
&code=YOUR_AUTHORIZATION_CODE
&redirect_uri=http://localhost:8080/callback

Ongoing Token Maintenance

• Access token expires every 24 hours
• Use refresh_token to get a new one without admin re-authorization
• After refreshing, update the Bearer token in claude_desktop_config.json
• Restart Claude Desktop after updating the config

───────────────────────────────────────────────

The Gong MCP server is currently in Beta. The connection URL will change from https://api.gong.io/mcp/message to https://mcp.gong.io after GA (expected Q2 2026). Update your Claude Desktop config accordingly when that happens.