{"site":{"name":"Koji","description":"AI-native customer research platform that helps teams conduct, analyze, and synthesize customer interviews at scale.","url":"https://www.koji.so","contentTypes":["blog","documentation"],"lastUpdated":"2026-11-16T00:58:31.465Z"},"content":[{"type":"documentation","id":"7934535e-b989-4cb3-86b3-2f2736869d7a","slug":"mcp-authentication-security","title":"MCP Authentication & Security","url":"https://www.koji.so/docs/mcp-authentication-security","summary":"Technical documentation of Koji MCP authentication using OAuth 2.1 with PKCE. Covers the complete authorization flow, token lifecycle, security model including study configuration access, data access scope, privacy protections, revocation process, supported OAuth standards, and full endpoint reference at koji.so.","content":"## Authentication Overview\n\nKoji 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.\n\nThere are no API keys to manage, no secrets in config files, and no credentials stored on your machine.\n\n---\n\n## How the OAuth Flow Works\n\nWhen you connect Koji to Claude (or any MCP client), here is what happens:\n\n### 1. Discovery\nThe MCP client reads Koji's OAuth configuration from a well-known endpoint:\n```\nhttps://www.koji.so/.well-known/oauth-authorization-server\n```\nThis tells the client where to send authorization requests, how to exchange tokens, and which security features are supported.\n\n### 2. Dynamic Client Registration\nThe client registers itself automatically via [RFC 7591](https://www.rfc-editor.org/rfc/rfc7591):\n```\nPOST https://www.koji.so/oauth/register\n```\nThis creates a unique client_id for the connection. No manual registration needed.\n\n### 3. Authorization Request\nThe client generates a PKCE code verifier and challenge, then opens your browser:\n```\nhttps://www.koji.so/oauth/authorize?\n  response_type=code\n  &client_id=...\n  &code_challenge=...\n  &code_challenge_method=S256\n  &redirect_uri=...\n  &scope=read:studies read:interviews read:account write:studies write:reports write:respondents\n```\n\n### 4. User Consent\nYou see a consent screen on koji.so showing:\n- The real name of the application that is asking, as it registered with Koji\n- Where your access will be sent once you approve\n- What permissions (scopes) it is requesting, with reading and making changes listed separately\n- Option to approve or deny\n\nKoji 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.\n\n### 5. Token Exchange\nAfter you approve, the client exchanges the authorization code for tokens:\n- **Access token** — Valid for 1 hour, used for API requests\n- **Refresh token** — Valid for 30 days, used to get new access tokens\n\n### 6. Automatic Refresh\nWhen 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.\n\n---\n\n## Token Lifecycle\n\n| Token Type | Lifetime | Purpose |\n|------------|----------|---------|\n| Authorization Code | 10 minutes | One-time code exchanged for tokens |\n| Access Token | 1 hour | Authenticates MCP requests |\n| Refresh Token | 30 days | Generates new access tokens |\n\n- **Token rotation**: Each refresh generates a new refresh token. The old one is invalidated.\n- **Revocation**: Revoking any token invalidates the entire token pair.\n- **One-time use**: Authorization codes can only be used once.\n\n---\n\n## Security Model\n\n### What Koji MCP Can Access\n\n| Data | Access Level |\n|------|-------------|\n| Your studies | Full read/write (owned studies only) |\n| Your interviews | Full read (owned studies only) |\n| Your transcripts | Full read (owned studies only) |\n| Your account info | Read-only (plan, usage, features) |\n| Your reports | Full read/write (owned studies only) |\n| Study configuration | Full read/write (branding, lead forms, settings) |\n| Other users' data | Never accessible |\n| Billing/payment info | Never accessible |\n| Password/credentials | Never accessible |\n\nWrite 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.\n\n### What Koji MCP Cannot Do\n\n- Access other users' studies or data\n- Read your password or authentication credentials\n- Make payments or change your billing\n- Access data from studies you do not own\n- Share your data with other users\n- Modify your account security settings\n\n### Data Privacy\n\n- **No training data**: Your research data is never used to train AI models\n- **Scoped access**: MCP only sees your studies, interviews, and account data\n- **Server-side validation**: Every request is validated against your user ID on the server\n- **Anti-injection protection**: All data returned from MCP includes integrity warnings to prevent prompt injection attacks\n\n---\n\n## Revoking Access\n\nYou can disconnect Koji from Claude at any time:\n\n### From Koji\n1. Go to [Koji Account Settings](https://www.koji.so/dashboard/profile)\n2. Find **Connected Applications**\n3. Click **Revoke** next to the connection\n\n### From Claude Desktop\n1. Open Settings then Integrations\n2. Find Koji\n3. Click **Disconnect**\n\nBoth methods immediately invalidate all tokens. You can reconnect at any time.\n\n---\n\n## Technical Reference\n\n### OAuth Endpoints\n\n| Endpoint | URL |\n|----------|-----|\n| Authorization Server Metadata | `https://www.koji.so/.well-known/oauth-authorization-server` |\n| Protected Resource Metadata | `https://www.koji.so/.well-known/oauth-protected-resource` |\n| Authorization | `https://www.koji.so/oauth/authorize` |\n| Token | `https://www.koji.so/oauth/token` |\n| Revocation | `https://www.koji.so/oauth/revoke` |\n| Dynamic Registration | `https://www.koji.so/oauth/register` |\n\n### Supported Standards\n\n- [OAuth 2.1](https://oauth.net/2.1/)\n- [PKCE (RFC 7636)](https://www.rfc-editor.org/rfc/rfc7636)\n- [Authorization Server Discovery (RFC 8414)](https://www.rfc-editor.org/rfc/rfc8414)\n- [Dynamic Client Registration (RFC 7591)](https://www.rfc-editor.org/rfc/rfc7591)\n- [Token Revocation (RFC 7009)](https://www.rfc-editor.org/rfc/rfc7009)\n\n### MCP Transport\n\n- **Protocol**: Streamable HTTP (Server-Sent Events)\n- **Endpoint**: `https://www.koji.so/api/mcp/mcp`\n- **Authentication**: Bearer token in Authorization header\n\n---\n\n## Related Documentation\n\n- **[MCP Setup Guide](/docs/mcp-setup-claude)** — Connect Koji to Claude step by step\n- **[MCP Overview](/docs/mcp-overview)** — Full integration overview\n- **[Tool Reference](/docs/mcp-tool-reference)** — All 15 MCP tools documented\n- **[API Authentication](/docs/api-authentication)** — REST API authentication (separate from MCP)\n\n\n---\n\n<!-- crosslink:dev-hub -->\n## Related: other ways to connect\n\nThe [Developer Hub](/docs/building-with-ai) 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](/docs/api-authentication) and [Starting Interviews via API](/docs/starting-interviews-via-api).\n","category":"Claude & MCP Integration","lastModified":"2026-10-06T16:04:44.780177+00:00","metaTitle":"MCP Authentication & Security — OAuth 2.1 with PKCE | Koji Documentation","metaDescription":"How Koji MCP authenticates AI assistants with OAuth 2.1 and PKCE. Covers authorization flow, token lifecycle, security model, data privacy, and access revocation.","keywords":["MCP OAuth authentication","PKCE security","AI tool security","OAuth 2.1 MCP","Koji security","MCP authentication flow","AI research data privacy"],"aiSummary":"Technical documentation of Koji MCP authentication using OAuth 2.1 with PKCE. Covers the complete authorization flow, token lifecycle, security model including study configuration access, data access scope, privacy protections, revocation process, supported OAuth standards, and full endpoint reference at koji.so.","aiPrerequisites":["Basic understanding of OAuth concepts (helpful but not required)"],"aiLearningOutcomes":["Understand how OAuth 2.1 with PKCE works in the MCP context","Know what data Koji MCP can and cannot access","Revoke access when needed","Understand the token lifecycle"],"aiDifficulty":"intermediate","aiEstimatedTime":"8 minutes"}],"pagination":{"total":1,"returned":1,"offset":0}}