feat(mcp-server): Add Notion MCP Server Support with Authentication

[divideby0]

Description

Add support for Notion MCP server to the fluent-toolkit registry with intelligent authentication handling using the self-hosted approach with integration tokens.

Background

Notion MCP supports two authentication approaches:

1. Self-hosted with Integration Token (our approach) - Uses NOTION_TOKEN env var with STDIO transport
2. Hosted OAuth via SSE - Notion's managed service at https://mcp.notion.com/mcp

We're implementing the self-hosted approach because it's simpler, more consistent with other MCP servers, and gives users full control over integration permissions.

Documentation: https://developers.notion.com/docs/mcp
GitHub Repository: https://github.com/makenotion/notion-mcp-server
npm Package: @notionhq/notion-mcp-server

Requirements

Authentication Detection

• Check if Notion MCP is already configured in user's .mcp.json
• If configured, detect whether NOTION_TOKEN is set in the server configuration
• Optionally validate token by making test API call to Notion API

Authentication Flow

• If not authenticated, guide user through Notion Integration setup:
  1. Direct user to https://www.notion.so/profile/integrations
  2. Instruct to create a new internal integration or select existing one
  3. Explain integration capabilities (read-only vs. full access)
  4. Guide user to connect pages/databases to the integration
  5. Prompt user to copy the integration token (ntn_****)
  6. Store token securely in .env.mcp.secrets (if available) or directly in .mcp.json env

MCP Configuration

• Generate proper .mcp.json configuration using STDIO transport (default):

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}

Note: The server defaults to STDIO transport which is what Claude Code expects. No need to specify --transport stdio explicitly.

CLAUDE.md Documentation

• Add Notion MCP usage instructions to CLAUDE.md
• Include examples of common operations:
  • Searching Notion workspace
  • Creating/updating pages
  • Querying databases
  • Adding comments
• Document integration capabilities and permissions

Implementation Details

Authentication Method: Self-Hosted with Integration Token

Why this approach:

• ✅ Simpler authentication flow (just paste integration token)
• ✅ Works with standard STDIO transport (no SSE complexity)
• ✅ No OAuth redirect handling required
• ✅ User has full control over integration permissions
• ✅ Consistent with other MCP servers in registry
• ✅ Works offline after initial setup

Token Format: Integration tokens start with ntn_ prefix

Authentication Detection Strategy

// Check if notion server exists in .mcp.json
const notionServer = mcpConfig.mcpServers?.notion;
const hasNotionToken = notionServer?.env?.NOTION_TOKEN;

if (!hasNotionToken) {
  // Launch interactive authentication flow
}

Token Validation (Optional Enhancement)

Test token validity with:

GET https://api.notion.com/v1/users/me
Headers:
  Authorization: Bearer {token}
  Notion-Version: 2022-06-28

Interactive Setup Flow

Use prompts to guide user through:

1. Creating Notion integration (with link to settings page)
2. Configuring integration capabilities (offer presets: read-only, full-access)
3. Connecting pages/databases to integration
4. Entering integration token
5. Validating token (optional, recommended)
6. Writing configuration to .mcp.json

Acceptance Criteria

• ftk init detects existing Notion MCP configuration
• User is guided through authentication if not configured
• Integration token is stored securely
• Generated .mcp.json uses STDIO transport (default)
• Configuration works with Claude Code out of the box
• CLAUDE.md includes Notion-specific usage instructions
• Error messages provide clear guidance for authentication issues

Questions for Implementation

1. Should we validate the token during setup (make API call) or trust user input?
   • Recommendation: Validate with optional skip flag for offline scenarios
2. Should we offer capability presets (read-only, full-access, custom)?
   • Recommendation: Yes, offer presets with explanation of each
3. How should we handle token expiration/rotation?
   • Recommendation: Provide clear error message directing user to refresh token

Related Documentation

• Notion MCP Overview
• Getting Started Guide
• Notion MCP Server GitHub
• Notion API Authorization

[divideby0]

Additional Requirement: Optional Server

Notion MCP should be marked as optional during ftk init.

Unlike core servers like basic-memory or sequential which the toolkit uses consistently, Notion integration is user-specific:

• ✅ Some users have Notion workspaces and want integration
• ✅ Others don't use Notion at all

Implementation Impact

1. Server Registry Classification:

   • Add optional: true flag to Notion server definition
   • Core servers (sequential, basic-memory): optional: false or required by default
   • User-specific servers (notion): optional: true

2. Init Flow:

   • Present Notion as an optional choice during server selection
   • User can skip Notion setup without breaking the workflow
   • Don't prompt for Notion authentication unless user explicitly selects it

3. Example Prompt:

   Select MCP servers to configure:
   ✓ Sequential Thinking (recommended)
   ✓ Basic Memory (recommended)
   ○ Notion (optional - integrate with your Notion workspace)
   

This ensures ftk init remains streamlined for users who don't use Notion while still offering easy setup for those who do.