How to connect the Koala AI MCP server
The Koala AI MCP server lets Claude, ChatGPT, Codex, Cursor and other AI assistants use Koala AI directly. Your assistant can research keywords, competitors and backlinks, read your Brand DNA and your own Search Console and Analytics data, and create articles in KoalaWriter.
The MCP is included with every paid plan, from Starter up. Free trial accounts can't connect an app.
The server URL is:
https://koala.sh/api/mcpYou'll find the same steps, with copy buttons, on koala.sh/mcp.
Connect your assistant
Each app opens a Koala AI sign-in page in your browser. Sign in to the Koala AI account that has your plan, choose what the app may access, and click the Allow button (it shows the app's name). Your Claude or ChatGPT email doesn't need to match your Koala AI email.
Claude Code
- Run this in your terminal:
claude mcp add --transport http koala-ai https://koala.sh/api/mcp- Start Claude Code, run
/mcp, and approve Koala AI in your browser.
claude.ai and the Claude app
- In claude.ai, open Customize → Connectors and click Add.
- Enter
Koala AIas the name, paste the server URL, and click Continue. - Leave the detected settings as they are and click Add.
- Click Connect, sign in to Koala AI, choose the permissions and approve.
- In a conversation, open + → Connectors and turn on Koala AI.
On Team and Enterprise workspaces, an owner may need to add the connector in the organization settings first.
ChatGPT
- In ChatGPT, open Settings → Security and login and turn on Developer mode.
- Open Plugins and click +. Enter
Koala AIas the name and paste the server URL into the Connection field. - Tick I understand and want to continue, then click Create.
- Click Sign in with Koala AI and confirm the permissions.
- Start a new conversation and select Koala AI from the tools menu.
If you don't see Developer mode, your ChatGPT plan or workspace admin may not allow custom connections.
Cursor
- On koala.sh/mcp, choose Cursor and click Add to Cursor.
- Let your browser open Cursor and confirm the install.
- Connect the server in Cursor and approve Koala AI in your browser.
Codex
- Run this in your terminal:
codex mcp add koala-ai --url https://koala.sh/api/mcp- Approve Koala AI in the browser window that opens.
- Restart your Codex session and run
/mcpto check the connection.
To sign in again later, run codex mcp login koala-ai.
Other MCP clients
Any client that supports remote HTTP MCP servers with OAuth can connect with the server URL.
Connect with an API key
Scripts and clients without browser sign-in can use a Koala AI API key. Create one under API Keys on your Account page and send it as a header:
Authorization: Bearer YOUR_API_KEYFor example, in Claude Code:
claude mcp add --transport http koala-ai https://koala.sh/api/mcp --header "Authorization: Bearer YOUR_API_KEY"An API key reaches every tool and every brand on your account. Browser sign-in lets you limit both. claude.ai only supports browser sign-in, so don't paste an API key there.
Choose what the app can do
The approval screen lists capability groups (for example Keywords, Backlinks, Brand DNA and calendar, Google performance, Create and edit articles, Generate images, Manage scheduled articles) and your brands. Tick only what you need: fewer tools take up less of your assistant's context.
To change this later, go to your Account page, find Connected apps, and click Permissions next to the app. Save, and the app picks up the change in its next session. Click Disconnect to remove an app.
What it costs
The MCP uses your plan's credits and words. There's no separate fee.
What the assistant does | Cost |
|---|---|
Read your brands, articles, usage, Search Console and Analytics; schedule articles; submit URLs for indexing | Free |
Fetch raw HTML, check robots.txt, search YouTube, Pinterest trends | 0.1 credits |
Read page text, sitemaps, screenshots, autocomplete, YouTube captions | 0.25 credits |
Live Google search results | 0.5 credits |
Keyword, competitor, traffic, authority, page analysis, AI Overview and Amazon lookups; article edits | 1 credit |
Keyword ideas and variations | 1 credit per seed keyword |
Backlink lookups | 2 credits |
Keyword volume, coverage checks, AI search opportunities | 3 credits |
Historical traffic | 4 credits |
Generate a standalone image | 1 credit (fast) or 8 credits (quality, Professional and higher) |
Create an article in KoalaWriter | Words, the same as writing it in the app |
Of the 62 tools, 23 are free. Articles your assistant creates go into your Article Queue, together with articles from the bulk writer and the API. Some features, such as Autopilot, still depend on your plan.
Fix connection problems
401 Unauthorized
- In claude.ai, remove the connector and add it again with browser sign-in. An API key won't work there.
- With an API key, check the header reads
Authorization: Bearerfollowed by the key, with no quotes or extra spaces, and that the key still exists on your Account page. - If you disconnected the app, or it says the token expired or was revoked, reconnect it. In Codex, run
codex mcp login koala-ai.
"authorization not found" or "This authorization request has expired"
The sign-in link was already used or timed out. Start the connection again from your assistant and finish the Koala AI sign-in in one go. If you have more than one Koala AI account, sign in to the one with the paid plan.
"The Koala AI MCP is available on paid plans"
The account you signed in with is on the free trial. Pick a plan on the pricing page, or sign in with your paid account, then approve again.
The app connects but shows no tools, or a tool is missing
- Check Connected apps → Permissions on your Account page. A connection with nothing ticked gets no tools.
- Search Console and Analytics tools appear only after you link Google to a brand in Brand DNA.
- Restart your assistant's session after changing permissions.
Still stuck? Contact support with the app you're connecting and the exact error.
Updated on: 09/11/2026
Thank you!