Koddi MCP Server — Help Center

Talk to your Koddi ads platform in plain English. The Koddi MCP server lets you connect AI assistants — Claude, ChatGPT, Cursor, Codex, and others — directly to your Koddi Ads platform, so you can ask questions, pull reports, and explore campaign data without leaving the chat window.

What is the Koddi MCP?

The Model Context Protocol (MCP) is an open standard that lets AI assistants securely connect to external applications — in this case, your Koddi platform. Once connected, the assistant can look up member groups, advertisers, campaigns, ad groups, creatives, targeting, financial balances, and run reports on your behalf.

You stay in control. The assistant only sees what your Koddi user account can see. Every request is authenticated as you, and access control is enforced by Koddi — not the AI tool.

What it is:

• A secure way to bring your Koddi data into an AI chat
• Read-only by default — safe for exploration, reporting, and analysis
• Works with any MCP-compatible AI client

What it isn’t:

• It is not a replacement for the Koddi UI
• It does not give the assistant access to anything your user doesn’t already have
• It does not share data between Koddi customers — each client has their own isolated connection

Before you start

Prerequisites

Get your MCP URL

Every Koddi customer gets a unique MCP URL tied to their account. It will look similar to this:

https://<your-client>.koddi.io/mcp

📘

If you don’t know what to use, ask your Koddi team - don’t guess. You won’t be able to authenticate with an incorrect URL.

Use the URL provided by your Koddi team. Throughout this guide, we’ll use retailer.koddi.io as a placeholder.

Setup by client

The Koddi MCP supports modern remote MCP clients out of the box. In every case the flow is the same:

1. Add the server URL (e.g. https://retailer.koddi.io/mcp) to your AI client. 2. Your browser opens to Koddi’s sign-on page. 3. Sign in with your normal Koddi credentials. 4. You’re redirected back to the client — done.

Claude (web & desktop)

Plan requirements: Available on Claude Pro, Max, Team, and Enterprise. On Team and Enterprise, a workspace Owner must add the connector first; members then connect individually.

Add the connector (individual — Pro/Max):

1. In Claude, open Settings -> Connectors.

   2. Click + Add custom connector.
   3. Paste your MCP URL: https://retailer.koddi.io/mcp
   4. Click Add. A browser window opens to sign in to Koddi.
   5. Sign in with your Koddi credentials and approve the connection.
   6. You’ll be redirected back to Claude. The connector is now listed as “Connected.”

   Add the connector (Team/Enterprise — Owner):

   1. Go to Organization settings -> Connectors.
   2. Click Add -> Custom -> Web.
   3. Enter the MCP URL and save.
   4. Members then open Settings -> Connectors, find the Koddi connector, and click Connect to complete sign-in for themselves.

Using it: When starting a chat, enable the Koddi connector from the tool menu. Then ask naturally: “Which campaigns did we run last month?”

Claude Code

Claude Code supports remote MCP servers natively.

One-off add (personal / this machine only):

claude mcp add --transport http koddi [https://retailer.koddi.io/mcp](https://retailer.koddi.io/mcp)

Claude Code will prompt you to authenticate in your browser the first time you invoke a tool. Run /mcp inside Claude Code to see the connection status and trigger sign-in manually if needed.

Project-level config (check into your repo):

Create .mcp.json in your project root:

{
  "mcpServers": {
    "koddi": {
      "type": "http",
      "url": "[https://retailer.koddi.io/mcp](https://retailer.koddi.io/mcp)"
    }
  }
}

Start Claude Code from that directory. On first use, it will open your browser to complete sign-on.

ChatGPT

Plan requirements: Custom MCP connectors require ChatGPT Pro, Business, Enterprise, or Edu. Developer Mode must be enabled in your workspace (admins configure this under Workspace Settings -> Permissions & Roles -> Connected Data).

Note: On Plus and Pro individual plans, ChatGPT restricts custom connectors to read-only use. That’s fine — the Koddi MCP is read-only, so you’re not missing anything.

Steps:

1. Enable Developer Mode: Settings -> Apps & Connectors -> Advanced settings -> Developer Mode.
2. Go to Settings -> Apps & Connectors -> Add new connector.
3. Fill in: Name: Koddi, Description: Koddi ads platform, MCP Server URL: https://retailer.koddi.io/mcp, Authentication: OAuth.
4. Check “I trust this application” and click Create.
5. Start a new chat. Open the connector tray and enable Koddi.
6. The first time you use a tool, ChatGPT opens a Koddi sign-in window. Sign in and approve.

OpenAI Codex CLI

Codex CLI supports streamable HTTP MCP servers.

Via command:

codex mcp add koddi --url [https://retailer.koddi.io/mcp](https://retailer.koddi.io/mcp)

Via config file (~/.codex/config.toml):

[mcp_servers.koddi]
enabled = true
transport = { type = "streamable_http", url = "[https://retailer.koddi.io/mcp](https://retailer.koddi.io/mcp)" }

On first tool call, Codex will open your browser to sign in.

Cursor

Add the server to Cursor’s MCP config file.

Global (~/.cursor/mcp.json) or project (.cursor/mcp.json):

{
  "mcpServers": {
    "koddi": {
      "url": "[https://retailer.koddi.io/mcp](https://retailer.koddi.io/mcp)"
    }
  }
}

Or use the UI: Cursor Settings -> Tools & MCP -> New MCP Server, paste the URL, and save. Cursor will prompt you to authenticate in the browser the first time.

Other MCP-compatible clients

The Koddi MCP supports the following MCP specification features, so any compliant client should work:

• Transport: HTTP Streamable (https://<your-client>.koddi.io/mcp)
• Auth: OAuth 2.1 with PKCE
• Dynamic Client Registration (RFC 7591) — the client doesn’t need to pre-register; it can register itself on first use
• Discovery endpoints: /.well-known/oauth-authorization-server, /.well-known/openid-configuration, /.well-known/oauth-protected-resource

If your MCP client requires manual OAuth config, point it at the MCP URL and let it discover everything from the well-known endpoints.

Your first conversation

Once connected, try one of these prompts to confirm everything works:

The assistant will walk you down the hierarchy — client -> advertiser -> campaign -> ad group — asking you to pick when there’s more than one option.

Sample workflows

What you can do

The Koddi MCP exposes ~60+ read-only tools covering the full Koddi platform. You don’t need to know the tool names — just ask naturally and the assistant picks the right one.

At a glance, here’s what’s available:

The assistant will tell you if something isn’t supported. If you find a gap that matters to your workflow, let your Koddi team know — new tools are added regularly.

Security & Privacy

How authentication works

1. Your AI client sends you to Koddi’s sign-on page (hosted by Koddi and your identity provider).
2. You sign in with your normal Koddi credentials — the AI client never sees your password.
3. Koddi issues a short-lived access token scoped to your user.
4. The MCP server uses that token to call Koddi on your behalf for every tool request.

Data access boundaries

• You can only see what you could already see. Koddi enforces access control server-side. The MCP server cannot grant access beyond your existing permissions.
• Each customer is isolated. Every Koddi customer connects to their own dedicated subdomain. Cross-customer data access is not possible — it is blocked at the network layer and re-validated on every request.
• Sessions are short-lived. Access tokens are refreshed automatically in the background while you’re active and expire within 24 hours of inactivity.

What the AI sees

The AI client sees:

• The tool responses (campaign data, reports, etc.) — same as you’d see in Koddi.
• The AI client does not see:
  • Your password
  • Long-lived credentials
  • Any other Koddi customer’s data

What Koddi logs

Koddi logs MCP requests the same way it logs normal platform API requests — for observability, security, and support. Logs never include your password or long-lived tokens.

Revoking access

Revoke access the same way you’d remove any OAuth-connected app:

• Claude: Settings -> Connectors -> Koddi -> Disconnect
• ChatGPT: Settings -> Apps & Connectors -> Koddi -> Disconnect
• Claude Code / Codex / Cursor: remove the entry from the config file

To fully revoke at the Koddi level, contact your Koddi team.

Limits & quotas

📘

Rate limits apply per user, not per client. They are designed to protect the Koddi platform from runaway agents. If you’re regularly hitting limits during normal use, reach out — we can review your usage.

FAQ

Common Gotchas

Troubleshooting

Getting help

If you encounter anything unexpected (or anything unexpectedly great!), please reach out to your Koddi team. We’d be happy to help.