Connect Koji to Claude (Setup Guide)

Prerequisites

Before you start, make sure you have:

1. A Koji account — Sign up free if you do not have one
2. Claude Desktop (recommended) or another MCP-compatible client
3. An active internet connection — OAuth requires connecting to koji.so

---

Option 1: Connect via Claude Desktop (Recommended)

Claude Desktop has built-in MCP support. Here is how to connect:

Step 1: Open Claude Desktop Settings

1. Open Claude Desktop
2. Click your profile icon in the bottom left
3. Select Settings → Integrations (or Developer → MCP Servers on older versions)

Step 2: Add Koji as an MCP Server

Click "Add MCP Server" or "Edit Config" and add the following configuration:

{
  "mcpServers": {
    "koji": {
      "url": "https://www.koji.so/api/mcp/sse"
    }
  }
}

That is the entire configuration. No API keys, no environment variables.

Step 3: Authorize Your Account

1. Save the configuration and restart Claude Desktop
2. Claude will show a Koji connection prompt
3. Click Connect — this opens your browser
4. Sign into your Koji account (if not already signed in)
5. Click Authorize to grant Claude access
6. You will be redirected back — the connection is now active

Step 4: Verify the Connection

In a new Claude conversation, type:

"List my Koji studies"

If you see your studies (or a message that you have no studies yet), the connection is working.

---

Option 2: Connect via Claude.ai (Browser)

Claude.ai supports MCP integrations through its web interface:

1. Go to claude.ai
2. Navigate to Settings → Integrations
3. Search for Koji or add a custom MCP server
4. Enter the server URL: https://www.koji.so/api/mcp/sse
5. Complete the OAuth authorization flow
6. Start using Koji tools in any conversation

---

Option 3: Connect via Cursor

Cursor supports MCP servers for AI-assisted development:

1. Open Cursor Settings (⌘ + , on Mac)
2. Go to MCP Servers
3. Click Add Server
4. Enter:
   • Name: Koji
   • URL: https://www.koji.so/api/mcp/sse
5. Save and authorize when prompted

---

Option 4: Connect via Any MCP Client

For any client that supports the Model Context Protocol:

• Server URL: https://www.koji.so/api/mcp/sse
• Transport: Streamable HTTP (SSE)
• Authentication: OAuth 2.1 with PKCE (auto-discovered via /.well-known/oauth-authorization-server)
• Scopes: read:studies, read:interviews, read:account

The server supports OAuth 2.0 Authorization Server Discovery (RFC 8414) and Dynamic Client Registration (RFC 7591), so compatible clients will auto-configure.

---

Troubleshooting

"Authentication required" errors

Your OAuth token may have expired. Most MCP clients auto-refresh, but if not:

1. Remove the Koji server from your client
2. Re-add it and re-authorize

Connection timeout

Make sure you can reach https://www.koji.so in your browser. If you are behind a corporate firewall, you may need to allowlist the domain.

"Study not found" errors

MCP only shows studies owned by the authenticated account. Make sure you are signed into the correct Koji account.

Claude does not show Koji tools

1. Verify the server URL is exactly https://www.koji.so/api/mcp/sse
2. Restart Claude Desktop after adding the configuration
3. Check that the OAuth authorization completed successfully

---

What to Try First

Once connected, try these commands to explore your account:

"What studies do I have in Koji?"

"Show me my account details and plan"

"Create a new customer discovery study about why enterprise users need single sign-on"

"Get the latest interviews from my most recent study"

---

Disconnecting

To revoke Koji's access:

1. Go to your Koji account settings
2. Find the Connected Apps section
3. Click Revoke next to the Claude connection

This immediately invalidates all tokens. You can reconnect at any time by repeating the setup process.

---

Next Steps

• Tool Reference — Learn what each of the 17 tools does
• Product Manager Workflow — End-to-end guide for PMs
• Best Practices — Tips for getting the most out of MCP