Skip to content

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 ​

  1. Claude connects to the MCP endpoint and receives a 401 Unauthorized response with a WWW-Authenticate: Bearer header.

  2. OAuth discovery — Claude fetches /.well-known/oauth-protected-resource/mcp to find the authorization server, then /.well-known/oauth-authorization-server for endpoint details.

  3. 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_id is an https URL the client controls, and this server reads the client's metadata (name, redirect URIs, grant types) from that URL. The server advertises this with client_id_metadata_document_supported: true. The document must say client_id equal to its own URL, list redirect_uris, and use no shared secret; none is assumed, private_key_jwt with jwks or jwks_uri is 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.

  4. Login — A browser window opens showing the Knowify login page. You enter your email and password, which are verified against the Knowify backend.

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

  6. 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 ​

TokenLifetimePurpose
Access token (JWT)8 hoursAuthenticates MCP requests
Refresh token14 days, sliding on useRenews access tokens without re-login
Grant60 days from consentThe 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 (aud must be https://developer.knowify.com/api, which only portal-registered clients may request) — presenting one there gets a 401 naming the resource to 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/mcp

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

  1. Go to Settings > Integrations (or look for the MCP / Connectors section)
  2. Click Add Custom Connector
  3. Enter the server URL: https://assistant.knowify.com/api/v2/mcp
  4. 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.