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 both of these:
A Koongo account with at least one project (your store connected and imported).
An AI client installed on your computer (Claude Code, Claude Desktop, Cursor, Gemini CLI, ChatGPT, …).
Koongo MCP is available to every Koongo account - no request or approval needed. It is currently in beta, so tools and behaviour may still change. Just connect your AI client (below) and log in with your Koongo account when prompted.
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 sign you in to the same account - OAuth just replaces the copy-paste with a browser login.
Getting a static token (only for the token method)
Sign in to Koongo and open MCP for AI in the left sidebar menu.
In the "Static API token" 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
Extension (recommended) - install the Koongo extension with a single command. It already contains the server URL and OAuth setup, so there is no config file to edit:
gemini extensions install https://github.com/koongo-com/gemini-cli-extension
On first use a browser window opens for the Koongo login and consent. If it does not open by itself, run /mcp auth koongo inside Gemini CLI. Add --auto-update to the install command to keep it current; you can also run gemini extensions update koongo or gemini extensions uninstall koongo at any time.
Manual config alternative - if you would rather configure it yourself, or you need a static token, edit ~/.gemini/settings.json. For OAuth, add just httpUrl:
{ "mcpServers": { "koongo": { "httpUrl": "https://mcp.koongo.com/mcp" } }}Then run /mcp auth koongo to open the browser login.
Static token - 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 | Make sure you're logged in to the correct Koongo account and completed the browser approval. If it persists, 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" | Make sure you're logged in to the correct Koongo account and completed the browser approval. If your account was suspended for MCP, contact Koongo support. |
401 / "unauthorized" | Your static token is wrong, expired or revoked. Generate a new one (MCP for AI → Static API token) 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). |