Appearance
MCP Authentication
The Knowify MCP server uses OAuth 2.0 to authenticate connections. When you connect from Claude, the OAuth flow is handled automatically — you just log in with your Knowify credentials.
The MCP endpoint is hosted on assistant.knowify.com, while the OAuth provider remains on developer.knowify.com.
How It Works
Step by Step
Claude connects to the MCP endpoint and receives a
401 Unauthorizedresponse with aWWW-Authenticate: Bearerheader.OAuth discovery — Claude fetches
/.well-known/oauth-protected-resource/mcpto find the authorization server, then/.well-known/oauth-authorization-serverfor endpoint details.Client identification — the client identifies itself in one of two ways, in this order of preference:
- Client ID Metadata Document (draft-ietf-oauth-client-id-metadata-document): the
client_idis anhttpsURL the client controls, and this server reads the client's metadata (name, redirect URIs, grant types) from that URL. The server advertises this withclient_id_metadata_document_supported: true. The document must sayclient_idequal to its own URL, listredirect_uris, and use no shared secret;noneis assumed,private_key_jwtwithjwksorjwks_uriis accepted. The MCP specification prefers this mechanism. - Dynamic client registration (RFC 7591) via
POST /oauth/reg, kept for clients that do not publish a metadata document. The MCP specification lists it as deprecated.
Either way no manual setup is needed, and clients identified this way can only obtain tokens for MCP server audiences.
- Client ID Metadata Document (draft-ietf-oauth-client-id-metadata-document): the
Login — A browser window opens showing the Knowify login page. You enter your email and password, which are verified against the Knowify backend.
Token exchange — After login, Claude receives an authorization code and exchanges it for a JWT access token. The token includes your scopes and a resource indicator for the MCP server.
Authenticated session — Claude includes the JWT in all subsequent MCP requests. The server validates the token, resolves your Knowify session, and routes tool calls to the backend on your behalf.
Token Lifecycle
| Token | Lifetime | Purpose |
|---|---|---|
| Access token (JWT) | 8 hours | Authenticates MCP requests |
| Refresh token | 14 days, sliding on use | Renews access tokens without re-login |
| Grant | 60 days from consent | The ceiling on one browser approval |
When your access token expires, Claude automatically refreshes it using the refresh token. You only need to re-login after 14 days without use, or 60 days after you first approved the connector.
Security
- PKCE (RFC 7636) — All MCP OAuth flows use Proof Key for Code Exchange with S256 challenge method.
- Resource Indicators (RFC 8707) — Access tokens are scoped to the MCP server resource (
/mcp). They are not valid on the REST API (audmust behttps://developer.knowify.com/api, which only portal-registered clients may request) — presenting one there gets a 401 naming theresourceto request. To call the REST API, register a client in the developers portal. - JWT verification — Every MCP request is verified against the OAuth server's JWKS endpoint.
- Scope enforcement — Tools check your granted scopes before executing. Read operations require
{resource}:read, write operations require{resource}:write. - Rate limiting — 120 requests per minute per client.
Connecting from Claude Code
Add the server to your project's .mcp.json:
json
{
"mcpServers": {
"knowify": {
"type": "url",
"url": "https://assistant.knowify.com/api/v2/mcp"
}
}
}Or connect interactively:
bash
claude /mcp
# Select "Add Server" → URL → https://assistant.knowify.com/api/v2/mcpOn first connection, a browser window will open for you to log in. After authentication, Knowify resources will be available in your Claude session.
Connecting from Claude.ai
- Go to Settings > Integrations (or look for the MCP / Connectors section)
- Click Add Custom Connector
- Enter the server URL:
https://assistant.knowify.com/api/v2/mcp - Follow the login prompt to authenticate with your Knowify credentials
Troubleshooting
"Authentication Error: access_denied"
This usually means a stale browser session from a previous failed login attempt. Clear your cookies for the OAuth server domain and try again.
"Authentication required" on tool calls
Your access token has expired and could not be refreshed. Disconnect and reconnect the MCP server to re-authenticate.
"Insufficient scope" on tool calls
Your token doesn't include the required scope for this operation. This can happen if the OAuth client was registered with restricted scopes. Reconnect to get a fresh token with the correct scopes.