MCP Authentication & Security

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

4. User Consent

You see a consent screen on koji.so showing:

• Which application is requesting access
• What permissions (scopes) it is requesting
• Option to approve or deny

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 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

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

Supported Standards

• OAuth 2.1
• PKCE (RFC 7636)
• Authorization Server Discovery (RFC 8414)
• Dynamic Client Registration (RFC 7591)
• Token Revocation (RFC 7009)

MCP Transport

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

---

Related Documentation

• MCP Setup Guide — Connect Koji to Claude step by step
• MCP Overview — Full integration overview
• Tool Reference — All 15 MCP tools documented
• API Authentication — REST API authentication (separate from MCP)