notion-mcp_skill

Overview

This skill provides a managed-authentication bridge to Notion via MCP (Model Context Protocol). It lets agents search workspaces, fetch pages and databases, create and update pages and databases, move or duplicate content, and manage comments and users using an authenticated gateway.

How this skill works

Requests are proxied through a Maton gateway that injects managed credentials and maintains MCP sessions via the Mcp-Session-Id header. All calls use POST to endpoint patterns like https://gateway.maton.ai/notion/{tool-name} and require an Authorization header with your MATON_API_KEY. You can list, create, and manage Notion MCP connections at the Maton control endpoint and specify a connection with the Maton-Connection header.

When to use it

• Programmatic access to Notion workspaces when you want managed authentication and session handling.
• Search across workspace pages, databases, and connected services via an MCP search tool.
• Create, update, move, duplicate, or delete pages and databases from an automated agent.
• Fetch full page or database content, including discussions and comments, for processing or summarization.
• Manage comments, list users or teams, or update data-source metadata through MCP endpoints.

Best practices

• Store MATON_API_KEY in environment variables and never hard-code it in code or logs.
• Reuse Mcp-Session-Id between requests to avoid repeated session initialization and speed up workflows.
• Specify Maton-Connection when multiple connections exist to ensure the correct MCP connection is used.
• Use the appropriate tool name (notion-search, notion-fetch, notion-create-pages, etc.) for each action and follow the schema for each endpoint.
• Test commands in a staging workspace before running bulk create/update operations in production.

Example use cases

• Search the workspace for all meeting notes about Q1 and fetch the most relevant pages for summarization.
• Create a project tracking database with a SQL DDL schema and then insert tasks into that database automatically.
• Update a page’s properties and replace or insert content programmatically during a document generation workflow.
• Move or duplicate pages when reorganizing a workspace, preserving properties and content.
• Retrieve comments on a page and post reviewer replies as part of an automated review assistant.