This page shows how to connect an AI client to the Koongo MCP server. You can sign in two ways - OAuth (a browser login, nothing to copy - recommended) or a static token. Most setup is a small edit to one text (config) file - pick your client below and copy the snippet.
1. Before you start
You need all three of these:
A Koongo account with at least one project (your store connected and imported).
Closed-beta access. Request it at https://mautic.koongo.com/mcp-closed-beta - enter your email and the public IP address you will connect from. We add that IP to the allow-list.
An AI client installed on your computer (Claude Code, Claude Desktop, Cursor, Gemini CLI, ChatGPT, …).
No VPN is needed. You connect over the normal internet once your IP is on the allow-list. If your internet IP changes (new office, home vs. work, dynamic ISP), simply submit the form again with the new IP.
Not sure what your public IP is? Ask the web: search "what is my IP", or open https://ifconfig.me.
2. Two ways to sign in
Method | Best for | How it feels |
OAuth (recommended) | Everyday use in any supported client. | You add the server URL, a browser window opens, you log in to Koongo and approve once. Nothing to copy or store, and you can revoke access anytime. |
Static token (Bearer) | Headless setups, automation / CI, or a client where the browser login is inconvenient. | You generate a token once and paste it into the client's config. You manage it yourself. |
Both methods still need your account on the closed-beta allow-list (step 1) and MCP enabled on your account. OAuth doesn't skip those - it just replaces the copy-paste with a browser login.
Getting a static token (only for the token method)
Sign in to Koongo and open My Account → Security.
In the "MCP API Access" box, click Generate token.
Copy the token immediately - it is shown only once. Store it like a password.
The token acts on your account's projects. Keep it secret. You can Regenerate it (which revokes the previous one) or Revoke it at any time on the same page.
3. Connection details
Server URL |
|
Transport | Streamable HTTP |
What each client supports:
Client | OAuth (browser login) | Static token (Bearer) |
Claude Code (CLI) | ✅ recommended | ✅ |
Cursor | ✅ recommended | ✅ |
Gemini CLI | ✅ recommended | ✅ |
Claude Desktop / claude.ai | ✅ only option | ❌ |
ChatGPT connectors | ✅ only option | ❌ |
Any other MCP client (mcp-remote) | ✅ recommended | ✅ |
4. Set up your client
Claude Code (CLI)
OAuth (recommended) - add the server, then log in from the browser:
claude mcp add koongo --transport http https://mcp.koongo.com/mcp
On first use, run /mcp inside Claude Code and choose to authenticate - a browser window opens for the Koongo login and consent. The config is saved to ~/.claude.json (Windows: %USERPROFILE%\.claude.json).
Static token alternative - add an Authorization header instead of logging in (keep the whole value quoted so the space is not split):
claude mcp add koongo --transport http --header "Authorization: Bearer YOUR_TOKEN" https://mcp.koongo.com/mcp
Or edit ~/.claude.json by hand - omit headers for OAuth, include it for the token:
{
"mcpServers": {
"koongo": {
"type": "http",
"url": "https://mcp.koongo.com/mcp",
"headers": { "Authorization": "Bearer YOUR_TOKEN" }
}
}
}Cursor
OAuth (recommended) - edit ~/.cursor/mcp.json with just the URL (no headers):
{
"mcpServers": {
"koongo": {
"url": "https://mcp.koongo.com/mcp"
}
}
}Open Settings → MCP; the Koongo server shows a Login / Needs authentication button - click it to log in via the browser.
Static token alternative - add a headers block:
{
"mcpServers": {
"koongo": {
"url": "https://mcp.koongo.com/mcp",
"headers": { "Authorization": "Bearer YOUR_TOKEN" }
}
}
}Gemini CLI
OAuth (recommended) - edit ~/.gemini/settings.json with just httpUrl:
{
"mcpServers": {
"koongo": {
"httpUrl": "https://mcp.koongo.com/mcp"
}
}
}In Gemini CLI run /mcp auth koongo to open the browser login.
Static token alternative - add a headers block (paste the real token; this file does not expand environment variables):
{
"mcpServers": {
"koongo": {
"httpUrl": "https://mcp.koongo.com/mcp",
"headers": { "Authorization": "Bearer YOUR_TOKEN" }
}
}
}Claude Desktop / claude.ai
OAuth (the only option here). Open Settings → Connectors → Add custom connector, paste https://mcp.koongo.com/mcp, and complete the browser login. There is no token to paste.
File-editing fallback (Desktop only, if the custom-connector option is not available to you): bridge to the server with mcp-remote. Edit claude_desktop_config.json - with no --header, mcp-remote runs the OAuth browser login itself:
{
"mcpServers": {
"koongo": {
"command": "npx",
"args": ["-y", "mcp-remote@latest", "https://mcp.koongo.com/mcp"]
}
}
}Where the file lives:
OS | Path |
macOS |
|
Windows |
|
Linux |
|
Restart Claude Desktop after saving. Using mcp-remote requires Node.js 18+ installed.
ChatGPT
OAuth (the only option). In a workspace that allows connectors, open Settings → Connectors, add the server URL https://mcp.koongo.com/mcp, and complete the browser login. Pasted tokens are not accepted.
Any other MCP client (mcp-remote bridge)
For a client that can only launch a local command (stdio), bridge to our HTTP endpoint with mcp-remote. This is also the route to use if your client struggles with the direct HTTP connection.
OAuth (recommended) - no header; mcp-remote opens the browser login and caches the tokens in ~/.mcp-auth:
{
"mcpServers": {
"koongo": {
"command": "npx",
"args": ["-y", "mcp-remote@latest", "https://mcp.koongo.com/mcp"]
}
}
}Static token alternative - pass the header:
{
"mcpServers": {
"koongo": {
"command": "npx",
"args": ["-y", "mcp-remote@latest", "https://mcp.koongo.com/mcp", "--header", "Authorization: Bearer YOUR_TOKEN"]
}
}
}Requires Node.js 18+. Always keep mcp-remote@latest (it includes an important security fix). On Windows, if the token looks split, keep the header exactly as one quoted string.
5. Check it works
Open a chat in your client and type:
List my Koongo projects.
If the assistant returns your project (or a list of projects), you are connected. Now head to Overview & Concepts or jump straight to a task guide.
6. Troubleshooting
A word on "SSE". Koongo uses the modern Streamable HTTP transport at /mcp. The older HTTP+SSE transport is deprecated and is not served. If a client only offers an "SSE" option or a /sse URL, don't point it there - use the mcp-remote bridge (above), which speaks the modern transport for it.
Symptom | Cause & fix |
Client wants an "SSE" URL, or | The old HTTP+SSE transport is not served. Use |
OAuth window doesn't open / "authorization required" | Log in to Koongo in your browser first, then trigger the client's login again (e.g. |
OAuth "access denied" / consent fails | Your account may not be MCP-enabled yet (closed beta). Make sure you requested access and were approved - contact Koongo support. |
Login used to work, now it loops or won't re-authorize (mcp-remote) |
|
mcp-remote: "port in use" / login hangs | To finish OAuth, |
Connects, but tool calls hang / never respond | A corporate proxy, VPN or firewall may be buffering the streaming (SSE) response so nothing reaches the client. Try a different network, or use the |
403 / "forbidden" / "not allowed" | Your IP is not on the allow-list, or it changed - re-submit the beta form with your current public IP. If the IP is correct, MCP may not be enabled on your account yet - contact Koongo support. |
401 / "unauthorized" | Your static token is wrong, expired or revoked. Generate a new one (My Account → Security → MCP API Access) and update your config - or switch to OAuth. |
Tools missing / nothing happens | Fully restart the client after editing its config, and check the JSON is valid (no trailing commas, matching braces). |