Back to docs
Claude & MCP Integration

MCP Authentication & Security

How Koji MCP authenticates with OAuth 2.1 and PKCE. Covers the authorization flow, token lifecycle, security model, data privacy, and how to revoke access.

Authentication Overview

Koji MCP uses OAuth 2.1 with PKCE (Proof Key for Code Exchange) — the most secure standard for authorizing AI assistants. This is the same security model used by GitHub, Google, and other enterprise platforms.

There are no API keys to manage, no secrets in config files, and no credentials stored on your machine.


How the OAuth Flow Works

When you connect Koji to Claude (or any MCP client), here is what happens:

1. Discovery

The MCP client reads Koji's OAuth configuration from a well-known endpoint:

https://www.koji.so/.well-known/oauth-authorization-server

This tells the client where to send authorization requests, how to exchange tokens, and which security features are supported.

2. Dynamic Client Registration

The client registers itself automatically via RFC 7591:

POST https://www.koji.so/oauth/register

This creates a unique client_id for the connection. No manual registration needed.

3. Authorization Request

The client generates a PKCE code verifier and challenge, then opens your browser:

https://www.koji.so/oauth/authorize?
  response_type=code
  &client_id=...
  &code_challenge=...
  &code_challenge_method=S256
  &redirect_uri=...
  &scope=read:studies read:interviews read:account write:studies write:reports write:respondents

4. User Consent

You see a consent screen on koji.so showing:

  • The real name of the application that is asking, as it registered with Koji
  • Where your access will be sent once you approve
  • What permissions (scopes) it is requesting, with reading and making changes listed separately
  • Option to approve or deny

Koji refuses any request it cannot verify, including one whose return address does not exactly match the registered application. Reading (read:studies, read:interviews, read:account) and making changes (write:studies, write:reports, write:respondents) are separate permissions: an assistant only gets the tools for the permissions you approved, so a connection you approved for reading cannot make changes on your behalf.

5. Token Exchange

After you approve, the client exchanges the authorization code for tokens:

  • Access token — Valid for 1 hour, used for API requests
  • Refresh token — Valid for 30 days, used to get new access tokens

6. Automatic Refresh

When the access token expires, the client automatically uses the refresh token to get a new pair. This happens transparently — you do not need to re-authorize.


Token Lifecycle

Token TypeLifetimePurpose
Authorization Code10 minutesOne-time code exchanged for tokens
Access Token1 hourAuthenticates MCP requests
Refresh Token30 daysGenerates new access tokens
  • Token rotation: Each refresh generates a new refresh token. The old one is invalidated.
  • Revocation: Revoking any token invalidates the entire token pair.
  • One-time use: Authorization codes can only be used once.

Security Model

What Koji MCP Can Access

DataAccess Level
Your studiesFull read/write (owned studies only)
Your interviewsFull read (owned studies only)
Your transcriptsFull read (owned studies only)
Your account infoRead-only (plan, usage, features)
Your reportsFull read/write (owned studies only)
Study configurationFull read/write (branding, lead forms, settings)
Other users' dataNever accessible
Billing/payment infoNever accessible
Password/credentialsNever accessible

Write access in the table above applies only when you approved the matching change permission. Connections made before September 21, 2026 keep their read access; to let one of them make changes, disconnect and reconnect it, then approve the change permissions.

What Koji MCP Cannot Do

  • Access other users' studies or data
  • Read your password or authentication credentials
  • Make payments or change your billing
  • Access data from studies you do not own
  • Share your data with other users
  • Modify your account security settings

Data Privacy

  • No training data: Your research data is never used to train AI models
  • Scoped access: MCP only sees your studies, interviews, and account data
  • Server-side validation: Every request is validated against your user ID on the server
  • Anti-injection protection: All data returned from MCP includes integrity warnings to prevent prompt injection attacks

Revoking Access

You can disconnect Koji from Claude at any time:

From Koji

  1. Go to Koji Account Settings
  2. Find Connected Applications
  3. Click Revoke next to the connection

From Claude Desktop

  1. Open Settings then Integrations
  2. Find Koji
  3. Click Disconnect

Both methods immediately invalidate all tokens. You can reconnect at any time.


Technical Reference

OAuth Endpoints

EndpointURL
Authorization Server Metadatahttps://www.koji.so/.well-known/oauth-authorization-server
Protected Resource Metadatahttps://www.koji.so/.well-known/oauth-protected-resource
Authorizationhttps://www.koji.so/oauth/authorize
Tokenhttps://www.koji.so/oauth/token
Revocationhttps://www.koji.so/oauth/revoke
Dynamic Registrationhttps://www.koji.so/oauth/register

Supported Standards

MCP Transport

  • Protocol: Streamable HTTP (Server-Sent Events)
  • Endpoint: https://www.koji.so/api/mcp/mcp
  • Authentication: Bearer token in Authorization header

Related Documentation


<!-- crosslink:dev-hub -->

Related: other ways to connect

The Developer Hub is the single starting point for every way to connect to Koji: the MCP server (this section), the REST Headless API, and the embed widget. For a code integration, see API Authentication and Starting Interviews via API.