Notion document store connectors

A document store connector is a connector with a docs block. It gives steps read-only context from specs, design notes, and runbooks. Text is converted to Markdown, cut to size, and fenced as outside data. A document store connector has no intake and no write-back.

The public example is Notion through Notion's official hosted MCP server.

Hosted MCP (Business and Enterprise)Copy Anchor Link

examples/connectors/notion/kusaw.yaml uses the hosted server at https://mcp.notion.com/mcp with a Notion MCP token as an Authorization bearer header secret. Because the server is hosted, kusaw validate warns that it is an outside service. Map search and fetch only; never a create or update tool. If a tool is not marked read-only, leave allow_unmarked off.

connectors:
  notion:
    mcp:
      url: https://mcp.notion.com/mcp
      headers:
        Authorization: { secret: true }
    docs:
      get: { tool: fetch, args: { id: "{{doc.id}}" }, text: text, title: title, url: url }
      search: { tool: search, args: { query: "{{task.title}}" }, results: results, id: id, max_results: 5 }
    agent_tools:
      - search
      - fetch

Store the token with kusaw config set --secret connectors.notion.mcp.headers.Authorization. The value is read from stdin or a hidden prompt and never written into kusaw.yaml.

Command connector fallback (other plans)Copy Anchor Link

Other Notion plans can use a command connector. You write a small program that answers tools and call for two read-only tools (search, and get a page) by calling Notion's public API with your own integration token, kept out of kusaw.yaml. The factory ships no such program.

connectors:
  notion:
    command: ["./notion-readonly"]
    env:
      NOTION_TOKEN: { secret: true }
    docs:
      get: { tool: get_page, args: { id: "{{doc.id}}" }, text: content, title: title, url: url }
      search: { tool: search_pages, args: { query: "{{task.title}}" }, results: results, id: id, max_results: 5 }
    agent_tools:
      - search_pages
      - get_page

Store the token with kusaw config set --secret connectors.notion.env.NOTION_TOKEN. Kusaw sets NOTION_TOKEN only in the connector's own process, where the program reads it from its environment, and replaces the value with [redacted] in any error or tool result the connector returns. Plain settings use { value: "..." }; a bare string is rejected. Never put the token itself in kusaw.yaml.

The program speaks the command-connector protocol on stdout. A tools invocation prints one JSON object listing the two read-only tools:

{"protocol":1,"tools":[{"name":"search_pages","description":"search pages","read_only":true},{"name":"get_page","description":"get a page","read_only":true}]}

A call invocation prints one JSON object with text content (and optional structured content):

{"content":[{"type":"text","text":"# Title\n\nPage body."}]}

Context entriesCopy Anchor Link

Steps list notion.task_docs, notion.fixed, and notion.search in steps.<id>.context. Task documents come from spec front matter docs: [notion:<id>] or from spec links whose host matches docs.link_hosts. Search uses {{task.title}} and {{task.labels.<key>}}.

kusaw docs show notion:<id> prints the converted, fenced text a step would get, with its size. kusaw connector call reaches the read tools the step allows. There is no new API or Dashboard screen.