How User Authentication Is Managed in the AI Job Search Application

The AI Job Search application delegates all user authentication to external services through Claude Code's MCP (Managed-Connector-Provider) layer rather than implementing custom authentication logic within the repository itself.

The MadsLorentzen/ai-job-search repository takes a security-first approach to user authentication by avoiding credential storage entirely. Instead of managing OAuth flows, API keys, or user sessions internally, the codebase relies on Claude Code's MCP integration to handle authentication for third-party services while keeping the repository free of sensitive materials.

Authentication Architecture Overview

The application follows a strict separation of concerns where authentication is performed outside the repository boundary. According to the source code, the repository contains no authentication implementation, no stored credentials, and no OAuth handling logic. Instead, command files verify that required MCP tools are available before proceeding, aborting gracefully with setup instructions when authentication prerequisites are missing.

This design ensures that:

• No secrets, tokens, or API keys are ever committed to version control
• OAuth exchanges happen entirely within Claude Code's managed environment
• Commands operate in a read-only manner with respect to authentication status

External Service Authentication via MCP

Protected integrations with Notion and Gmail rely entirely on Claude Code's MCP layer, which stores OAuth tokens and manages refresh cycles externally.

Notion Integration (.claude/commands/notion-sync.md)

The Notion synchronization command implements a two-step verification process defined in lines 26-34 of .claude/commands/notion-sync.md. First, it checks for the presence of Notion MCP tools using a helper function. If the tools are absent, the command outputs specific connection instructions and exits immediately without attempting to initiate an OAuth flow.

# Step 1: Preflight the Connection (Notion binding)

# 1. Verify Notion MCP tools are available in the session.

if not has_mcp_tool("notion"):
    # Graceful exit – user must run the MCP add command.

    print(
        "Notion MCP isn't connected. Run `claude mcp add --transport http notion "
        "https://mcp.notion.com/mcp`, then start a new session, run `/mcp` to "
        "complete the OAuth login, and re‑run `/notion‑sync`."
    )
    exit()

# 2. Verify the connection with a cheap call (e.g. workspace search).

if not notion_api_ok():
    print("Notion auth error – re‑authenticate via `/mcp` and stop.")
    exit()

The command verifies the OAuth token's validity by making a lightweight API call. If authentication has expired or failed, the user receives instructions to run claude mcp add and /mcp rather than the command handling the re-authentication itself.

Gmail Integration (.claude/commands/gmail-sync.md)

The Gmail sync workflow, defined in lines 11-14 of .claude/commands/gmail-sync.md, follows the same verification pattern. At Step 0, the command checks for the availability of mcp__claude_ai_Gmail__* tools before proceeding.

## Step 0: Prerequisites

Confirm the Gmail MCP tools (`mcp__claude_ai_Gmail__*`) are available.
If not, tell the user to connect the Gmail integration (claude.ai Settings → Connectors → Gmail)
and stop – do not attempt this via Bash, IMAP, or any other channel.

Like the Notion integration, the Gmail command never initiates an OAuth exchange. It only reads from the mailbox using the pre-authorized MCP connector. If the connector is unavailable, users must authenticate through the Claude AI Settings UI manually.

Public API Access for Job Portals

For job portal searches, the application deliberately avoids authentication entirely. The built-in CLI tools—including linkedin-search, jobindex-search, and freehire-search—query public, unauthenticated APIs as documented in the .agents/skills/**/SKILL.md files.

When users attempt to add custom portals that require authentication, the /add-portal command explicitly rejects the request. Lines 41-43 of .claude/commands/add-portal.md state:

- If the portal requires login/authentication to view listings, **stop**:
  this pattern only works on public pages. Tell the user and suggest checking
  whether the portal has an official API.

This restriction prevents the repository from handling credentials for third-party job sites and ensures compliance with terms of service by avoiding authenticated scraping.

Local Operations Without Authentication

Commands that interact with the local job tracker—including /apply, /outcome, and /rank—operate entirely on files within the repository. These commands read from and write to local storage without contacting external services, requiring no authentication mechanism whatsoever.

The application's README confirms this security stance in its dedicated security section, emphasizing that local file operations are sandboxed from external authentication requirements.

Summary

• No custom authentication: The application delegates all OAuth and credential management to Claude Code's MCP layer
• MCP verification pattern: Commands check for has_mcp_tool() or specific tool prefixes before executing external API calls
• Graceful degradation: When MCP tools are missing or unauthenticated, commands abort with specific setup instructions rather than failing mid-operation
• Public-only portals: Job portal integrations are restricted to unauthenticated public APIs, with explicit rejection of portals requiring login
• Zero secrets in repository: The codebase contains only [PLACEHOLDER] values and implements no credential storage

Frequently Asked Questions

Does the AI Job Search application store my passwords or API keys?

No. The repository contains no credential storage mechanism and no secrets management code. All tokens and OAuth state are managed externally by Claude Code's MCP layer. The source code only contains placeholder values and verification logic to confirm external tools are available before proceeding.

How do I authenticate with Notion or Gmail when using this application?

You must complete authentication through Claude Code's interface before running the sync commands. For Notion, run claude mcp add --transport http notion https://mcp.notion.com/mcp and then /mcp to complete the OAuth flow. For Gmail, navigate to claude.ai Settings → Connectors → Gmail. The application commands will verify these connections are active but will not initiate the login process themselves.

Why can't I add job portals that require login credentials?

The /add-portal command explicitly rejects portals requiring authentication to prevent terms-of-service violations and credential management complexity. The application is designed to work only with public, unauthenticated API endpoints. If you need to access a portal behind authentication, the documentation suggests checking whether that portal offers an official API with proper key-based access rather than attempting automated login through the tool.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}