> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://support.koala.sh/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# 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/mcp
```

You'll find the same steps, with copy buttons, on [koala.sh/mcp](https://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

1. Run this in your terminal:
   ```
   claude mcp add --transport http koala-ai https://koala.sh/api/mcp
   ```
2. Start Claude Code, run `/mcp`, and approve Koala AI in your browser.

### claude.ai and the Claude app

1. In claude.ai, open **Customize → Connectors** and click **Add**.
2. Enter `Koala AI` as the name, paste the server URL, and click **Continue**.
3. Leave the detected settings as they are and click **Add**.
4. Click **Connect**, sign in to Koala AI, choose the permissions and approve.
5. 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

1. In ChatGPT, open **Settings → Security and login** and turn on **Developer mode**.
2. Open **Plugins** and click **+**. Enter `Koala AI` as the name and paste the server URL into the **Connection** field.
3. Tick **I understand and want to continue**, then click **Create**.
4. Click **Sign in with Koala AI** and confirm the permissions.
5. 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

1. On [koala.sh/mcp](https://koala.sh/mcp), choose **Cursor** and click **Add to Cursor**.
2. Let your browser open Cursor and confirm the install.
3. Connect the server in Cursor and approve Koala AI in your browser.

### Codex

1. Run this in your terminal:
   ```
   codex mcp add koala-ai --url https://koala.sh/api/mcp
   ```
2. Approve Koala AI in the browser window that opens.
3. Restart your Codex session and run `/mcp` to 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](https://koala.sh/account) page and send it as a header:

```
Authorization: Bearer YOUR_API_KEY
```

For 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](https://koala.sh/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: Bearer` followed 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](https://koala.sh/pricing), 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](https://support.koala.sh/en/article/how-to-submit-a-ticket-and-join-our-discord-eke843/) with the app you're connecting and the exact error.