Notion MCP server: query your workspace from Claude, Cursor, and any AI agent

A lot of teams keep their docs in Notion — product specs, runbooks, onboarding guides, internal wikis. As AI agents become part of everyday engineering and product workflows, the natural next step is making that Notion content queryable: ask Claude a question and have it pull the answer from your actual workspace pages, not from its training data.

There are two ways to do this: the official Notion MCP server (for private workspace content that requires auth) and indexing public Notion pages via AgentReady (for public-facing docs that you want every AI agent to be able to query without credentials). This guide covers both.

Option 1: The official Notion MCP server

Notion ships an official MCP server that authenticates with the Notion API and exposes your private workspace content as MCP tools. This is the right approach when your Notion pages are private — internal docs, team wikis, project plans.

Step 1: Create a Notion integration

Go to notion.so/my-integrations → New integration. Give it a name (e.g. "Claude MCP"), select the workspace, and set the capabilities to Read content. Copy the internal integration secret — this is your NOTION_API_KEY.

Step 2: Share pages with the integration

The integration can only access pages you explicitly share with it. Open any Notion page → Share → search for your integration name → Invite. Do this for each page (or top-level database) you want agents to query. Child pages are included automatically.

Step 3: Add to your MCP client config

For Claude Desktop, open ~/Library/Application Support/Claude/claude_desktop_config.json and add:

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/mcp"],
      "env": {
        "NOTION_API_KEY": "secret_your_key_here"
      }
    }
  }
}

For Cursor, go to Settings → Features → MCP Servers → Add new MCP server, set transport to stdio, command to npx, args to -y @notionhq/mcp, and set the environment variable.

Restart the client. You should see Notion tools listed: notion_search, notion_get_page, notion_query_database, and others.

What the tools do

notion_search(query) — full-text search across shared pages. This is the primary tool for question-answering workflows.

notion_get_page(pageId) — retrieve the full content of a specific page by ID. Useful when the agent needs to read a complete document.

notion_query_database(databaseId) — query a Notion database with filters. Useful for structured data like project trackers, feature lists, or bug databases.

Limitations of the official server

The Notion MCP server works well for private workspace access, but it has real constraints for docs use cases:

Requires credentials everywhere. Every user who wants to query your docs needs their own API key, or you need to share a single integration key — which has access control implications.

Search is keyword-based. notion_search is Notion's built-in full-text search. It's not semantic — "how do I handle rate limiting" might not surface a page titled "API throttling" even if that page answers the question exactly.

No citations in answers. The tools return raw page content. The AI constructs an answer from it, but there's no built-in mechanism for cited, source-grounded responses.

Every query hits Notion's API in real time. For high-volume use (many agents, many queries), this creates rate limit pressure and latency.

Option 2: Index public Notion pages with AgentReady

Many teams publish their public docs on Notion — product documentation, API guides, changelogs, onboarding pages. If your Notion content is publicly accessible (shared publicly or published to the web), AgentReady can crawl and index it like any other website.

The advantage: semantic search, cited answers, no credentials required for anyone querying it, and compatibility with any MCP client through a single hosted endpoint.

To index a public Notion site:

# Via CLI
npx @agentreadyweb/mcp index https://your-notion-domain.notion.site

# Via the dashboard — paste the URL at agentready.it.com/dashboard

Once indexed, any MCP client connected to AgentReady can ask questions about your Notion content with cited answers pointing to the specific pages.

Note on Notion's JavaScript rendering: Notion pages are heavily JS-rendered. AgentReady uses a headless browser for crawling, so it handles Notion's client-side rendering correctly — static crawlers will often return empty pages for Notion content.

Which approach to use

Use the official Notion MCP server when your content is private and you want agents operating within your own tools (Claude Desktop, Cursor, internal automation) to read it. This is the right default for internal wikis, project docs, and team knowledge bases.

Use AgentReady when your Notion content is public-facing and you want any AI agent — your users' agents, not just your team's — to be able to query it with cited answers. Public product documentation, developer guides, and changelog pages are good candidates.

The two approaches aren't mutually exclusive. Many teams run both: private Notion MCP for internal access, AgentReady for the public docs surface that external developers are querying.