config

Instructions

Implementation Reference

• src/tools/composite/config.ts:10-15 (schema)

  ConfigInput interface defining the schema for the config tool: action (status|setup_start|setup_reset|setup_complete|set|cache_clear), force, key, value.

  export interface ConfigInput {
    action: 'status' | 'setup_start' | 'setup_reset' | 'setup_complete' | 'set' | 'cache_clear'
    force?: boolean
    key?: string
    value?: string
  }

• src/tools/composite/config.ts:20-107 (handler)

  Main handler function for the config tool. Manages credential state with actions: status, setup_start, setup_reset, setup_complete, set, cache_clear. Does not require a Notion client.

  export async function config(input: ConfigInput): Promise<any> {
    return withErrorHandling(async () => {
      switch (input.action) {
        case 'status': {
          const state = getState()
          const token = getSubjectToken()
          const publicUrl = process.env.PUBLIC_URL ?? null
          return {
            action: 'status',
            state,
            has_token: token !== null,
            setup_url: publicUrl ? `${publicUrl}/authorize` : null,
            token_source: token ? (process.env.NOTION_TOKEN ? 'environment' : publicUrl ? 'oauth' : 'relay') : null
          }
        }
  
        case 'setup_start': {
          // Post stdio-pure + http-multi-user split (2026-05-01): the
          // daemon-bridge relay setup spawn is gone. In stdio mode the
          // server requires NOTION_TOKEN env at startup. In HTTP mode the
          // OAuth flow lives at <PUBLIC_URL>/authorize served by the same
          // process -- no separate trigger needed.
          const publicUrl = process.env.PUBLIC_URL
          if (publicUrl) {
            return {
              action: 'setup_start',
              state: getState(),
              setup_url: `${publicUrl}/authorize`,
              message: `Open ${publicUrl}/authorize in your browser to complete the Notion OAuth flow.`
            }
          }
          return {
            action: 'setup_start',
            state: getState(),
            setup_url: null,
            message:
              'In stdio mode set NOTION_TOKEN env var in your MCP plugin config (get token from https://www.notion.so/my-integrations). To use HTTP/OAuth flow run with TRANSPORT_MODE=http and PUBLIC_URL set.'
          }
        }
  
        case 'setup_reset': {
          resetState()
          return {
            action: 'setup_reset',
            state: getState(),
            message: 'Credential state reset. Token cleared, config file deleted. Use setup_start to reconfigure.'
          }
        }
  
        case 'setup_complete': {
          const newState = await resolveCredentialState()
          return {
            action: 'setup_complete',
            state: newState,
            has_token: getSubjectToken() !== null,
            message:
              newState === 'configured'
                ? 'Credentials verified. Notion tools are ready.'
                : 'No credentials found. Use setup_start to begin relay setup.'
          }
        }
  
        case 'set': {
          return {
            action: 'set',
            ok: false,
            error: 'Notion has no mutable runtime settings. To update your token, use setup_reset then setup_start.'
          }
        }
  
        case 'cache_clear': {
          return {
            action: 'cache_clear',
            ok: true,
            cleared: 0,
            message: 'No client-side cache to clear. Notion API responses are not cached.'
          }
        }
  
        default:
          throw new NotionMCPError(
            `Unsupported action: ${(input as any).action}`,
            'VALIDATION_ERROR',
            'Valid actions: status, setup_start, setup_reset, setup_complete, set, cache_clear'
          )
      }
    })()
  }

• src/tools/registry.ts:387-421 (schema)

  MCP tool registration schema for 'config' - defines name, description, annotations, and inputSchema with action, force, key, value properties.

  {
    name: 'config',
    description:
      'Manage server configuration and credential state.\n\nActions:\n- status: current credential state, token source, setup URL\n- setup_start (-> force): trigger relay setup to configure Notion token via browser\n- setup_reset: clear credentials and config, return to awaiting_setup\n- setup_complete: re-check credentials after external config changes\n- set: update a runtime setting (notion has no mutable settings; returns info)\n- cache_clear: clear any cached state (no-op for notion)',
    annotations: {
      title: 'Config',
      readOnlyHint: false,
      destructiveHint: false,
      idempotentHint: false,
      openWorldHint: false
    },
    inputSchema: {
      type: 'object',
      properties: {
        action: {
          type: 'string',
          enum: ['status', 'setup_start', 'setup_reset', 'setup_complete', 'set', 'cache_clear'],
          description: 'Action to perform'
        },
        force: {
          type: 'boolean',
          description: 'Force setup_start even if already configured'
        },
        key: {
          type: 'string',
          description: 'Setting key (for set action)'
        },
        value: {
          type: 'string',
          description: 'Setting value (for set action)'
        }
      },
      required: ['action']
    }
  },

• src/tools/registry.ts:543-545 (registration)

  Routing case in CallToolRequestSchema handler that dispatches 'config' to the config() handler function.

  case 'config':
    result = await config(args as any)
    break

• src/tools/registry.ts:22-22 (registration)

  Import of the config function from the composite/config.ts module into the tool registry.

  import { config } from './composite/config.js'