Lesson 09 — Authentication & Secrets

OAuth, API keys, secret storage, per-user state — and how to keep them out of your logs.

MCP Servers Module 3

Why auth now

Until now, PKB has been single-user and trust-everything. The moment you ship a server over HTTP (Lesson 13), or want per-user data, or call paid third-party APIs from your tools — auth becomes mandatory.

This lesson covers the integration points; full OAuth provider implementation is its own topic.

Two distinct concerns

OAuth flow for remote MCP (overview)

1. Client → /authorize           (user grants consent)
2. Server → redirect with code
3. Client → /token (exchange code → access_token)
4. Client → MCP requests with `Authorization: Bearer <token>`
5. Server validates token per request

Standard OAuth 2.1 + PKCE; the MCP spec defines how the access token is attached to RPC frames.

Where the protocol meets auth

MCP requires the server to be able to refuse unauthenticated requests and to scope state by the authenticated principal.

The official Python SDK exposes hooks for this; FastMCP wraps them. We won't implement a full provider — we'll stub one and show the integration points.

API-key handling

import os
from mcp.server.fastmcp import FastMCP

THIRD_PARTY_KEY = os.environ.get("PKB_THIRD_PARTY_KEY")
if not THIRD_PARTY_KEY:
    raise SystemExit("PKB_THIRD_PARTY_KEY env var is required")

mcp = FastMCP("pkb", version="0.2.0")

• Env vars over config files.
• Never log the key.
• Rotate via deploy, not via config edit.

Per-user state pattern

Instead of a global NOTES dict, key state by the authenticated user:

NOTES[user_id][title] = body

The user id comes from the verified OAuth token (or from a stdio-context principal for local installs).

Stub auth provider for the lab

# pkb/auth.py
def get_current_user(ctx) -> str:
    """Return user id from ctx. Stub: reads from env, real impl reads OAuth claims."""
    user = os.environ.get("PKB_USER", "local")
    if not user:
        raise McpError(ErrorData(code=INVALID_PARAMS, message="not authenticated"))
    return user

This is the integration point — swap the stub for a real OAuth claim extractor when going remote.

The pkb.export tool

@mcp.tool()
def export(ctx: Context) -> dict[str, str]:
    """Export all of the current user's notes."""
    user = get_current_user(ctx)
    return USER_NOTES[user]

Gated by get_current_user; raises if no user — no auth bypass.

Secret storage

Never commit secrets; never echo them in tool responses.

Common pitfalls

What we'll build today

• Create pkb/auth.py with the stub get_current_user.
• Refactor NOTES to be per-user (USER_NOTES[user]).
• Add pkb.export() gated by auth.
• Verify it raises when PKB_USER is unset.

Recap & what's next

• Auth is two concerns — user-to-server and server-to-third-party.
• Stub the integration points before going remote.
• Never let secrets escape your process.