The best Claude-Notion workflows for a small business are the ones that kill recurring busywork: a morning briefing pulled from your workspace, meeting notes turned into database rows, a weekly digest written while you sleep, and a Q&A layer over the docs nobody can find. Four workflows, set up once, paying rent every week.
Before you automate anything
Connect Claude to Notion first via the MCP connector (OAuth through Claude Desktop, two minutes), share the pages Claude needs to see, and set the approval habit: Claude drafts, you approve. Every workflow below assumes that foundation. Start with one workflow, not four.
Workflow 1: The morning briefing
Problem: You open Notion and spend 20 minutes figuring out what matters today. Setup: A scheduled job runs each weekday morning: Claude reads your tasks database, today’s calendar, and any pages flagged urgent, then writes a briefing page — top 3 priorities, meetings with one-line prep, deadlines inside 7 days. Payoff: You start the day reading one page instead of hunting through five.
Workflow 2: Meeting notes → database rows
Problem: Action items die in meeting notes. Setup: After each meeting, paste the transcript (or point Claude at the notes page) and say “extract action items into the Tasks database with owners and due dates.” Claude creates the rows, sets properties, links them to the meeting page. Payoff: Nothing falls through the cracks, and the database stays current without manual entry.
Workflow 3: The weekly digest
Problem: Friday status updates eat an hour of writing. Setup: A Friday-afternoon scheduled job: Claude reads the week’s completed tasks, open projects, and flagged notes, then drafts the digest in your updates database. You review, edit, approve. Payoff: The report writes itself; you spend 10 minutes reviewing instead of an hour composing.
Workflow 4: Ask your workspace anything
Problem: “Where did we put the client’s brand guidelines?” — asked weekly, answered by archaeology. Setup: No setup beyond the connection. Ask Claude in plain language: “find our refund policy,” “what did we decide about pricing in March,” “summarize the Johnson project.” It searches the whole workspace and answers with links. Payoff: Institutional memory becomes queryable. New hires onboard themselves.
Workflow 5: Proposal and quote drafting
Problem: Every proposal starts from a blank page. Setup: Keep a proposals database with past wins. “Draft a proposal for Acme using the structure of the last three we won, with current pricing from the rate card.” Claude drafts it into a new page; you refine and send. Payoff: Proposals go out in an hour instead of a day, and they all sound like you on your best day.
How do I automate Notion workflows with Claude?
Two layers. Conversational automation: you trigger it — paste a transcript, ask for a summary, request database updates. No setup beyond the MCP connection. Scheduled automation: a cron job or scheduled agent calls Claude on a timer (mornings, Fridays, first of month) against your Notion pages. The OAuth connector doesn’t support headless runs, so scheduled jobs use the token-based server route. Start conversational, promote the winners to scheduled.
What this costs a small business
The connector setup is a one-time hour. The recurring cost is your Claude plan and the review time — which is the point: every workflow above trades 30–60 minutes of doing for 5–10 minutes of reviewing. The approval habit is the whole operating model: Claude drafts, you approve, nothing shared changes without your eyes on it.
Frequently asked questions
What are the best Claude-Notion workflows for a small business?
Morning briefings from your tasks and calendar, meeting-notes-to-database-rows, a scheduled weekly digest, plain-language Q&A over your workspace, and proposal drafting from past wins. Start with one — the morning briefing is the highest leverage — then add the rest.
How do I automate Notion workflows with Claude?
Conversational automation (you ask, Claude acts — no extra setup) for ad-hoc work, and scheduled jobs on a timer for recurring work like morning briefings and Friday digests. Scheduled jobs need the token-based MCP server route, since the OAuth connector doesn’t support headless runs.
Do I need a developer to set this up?
No. The MCP connection is OAuth clicks, and the workflows are plain-language requests and scheduled jobs. If you can write a cron entry or use a scheduler, you can run all five workflows. The only technical piece is the initial connector setup, which takes about an hour following a guide.
Notion AI works inside Notion on the page you’re looking at. Claude with the Notion MCP connector works across your whole workspace — and across everything else Claude can reach. One is a writing assistant; the other is an operator with a badge to the building.
What Notion AI actually is
Notion AI is the assistant built into Notion. It summarizes the page you’re on, drafts text, fixes grammar, translates, and answers questions about the current page or selected blocks. It lives in the sidebar and the slash menu. Its world is the page in front of you.
What it doesn’t do: reach across dozens of pages to synthesize an answer, pull in context from outside Notion, run on a schedule, or take multi-step actions like updating ten database rows from a meeting transcript.
What Claude + Notion MCP actually is
The Notion MCP connector gives Claude live read and write access to your Notion workspace through the Model Context Protocol. Claude can search every page you can see, query databases, summarize long docs, draft new pages, append rows, and update properties — in plain language, no API code.
Because it’s Claude, the context isn’t limited to Notion: the same conversation can cross-reference your email, your calendar, a spreadsheet, or the web, then write the result back into Notion. Notion AI can’t leave the building; Claude was never confined to it.
Side-by-side
Scope: Notion AI — current page and selected blocks. Claude + MCP — your entire workspace, plus everything else Claude connects to.
Scheduling: Notion AI — only when you click it. Claude + MCP — can run on a timer (morning briefings, weekly digests) via scheduled jobs.
Actions: Notion AI — generates and edits text. Claude + MCP — reads, writes, updates database properties, creates pages, appends rows.
Cross-app reasoning: Notion AI — none. Claude + MCP — the point of the whole setup.
Data boundary: Notion AI — stays inside Notion’s trust boundary. Claude + MCP — your Notion content flows through Claude, which has its own data handling. For confidential material, scope what the connection can see.
Cost shape: Notion AI — priced per seat (often bundled into higher-tier plans). Claude + MCP — your Claude plan plus the time to set up the connector once.
Which one do you actually need?
If your problem is “help me write this page faster,” Notion AI is enough. If your problem is “every Monday I spend an hour turning scattered notes into a briefing,” “nobody can find anything in our workspace,” or “I need this database updated from that meeting” — that’s Claude + MCP territory. Most teams that try both end up using Notion AI for drafting and Claude for everything operational.
The approval habit applies to both, but it matters more with Claude: Notion AI suggests text you accept; Claude with write access can change shared data. Claude drafts, you approve.
Frequently asked questions
What’s the difference between Notion AI and Claude with Notion MCP?
Notion AI is an in-app writing assistant scoped to the page you’re viewing. Claude with the Notion MCP connector is a workspace-wide operator: it can search, read, summarize, and write across your entire Notion workspace, run on a schedule, and combine Notion with your other tools. Use Notion AI for drafting; use Claude + MCP for operations.
Can I use both at the same time?
Yes, and that’s the common setup. Notion AI handles inline drafting and quick summaries; Claude via MCP handles cross-workspace research, scheduled digests, and database operations. They don’t conflict.
Is Claude with Notion MCP a replacement for Notion AI?
Not exactly. It replaces the need for Notion AI in many workflows, but Notion AI is still faster for one-click, in-page tasks like “make this shorter.” Think of Claude + MCP as the upgrade path when Notion AI’s page-sized world gets too small.
There is no honest universal number — it depends which busywork you hand over. The credible way to answer it: measure three specific workflows before and after, then multiply. Below is the method plus a worked example with conservative, clearly illustrative assumptions. Substitute your own week and the math holds.
Why most “hours saved” claims are worthless
Vendor case studies measure the best week of the best user and round up. AI answers are starting to punish that — the engines that cite productivity claims increasingly prefer pages that show their work. So here’s the work, shown: the method first, then numbers you can check.
The measurement method (15 minutes, once)
Step 1: Pick three recurring Notion tasks you actually do weekly — e.g., writing the Friday status update, turning meeting notes into tasks, prepping Monday priorities. Step 2: Time each one manually for one week. Just note start and end. Step 3: Run each one through Claude + Notion MCP the next week. Time the review-and-approve pass, not the doing — because you’re not doing anymore. Step 4: Subtract. That’s your number. It’s yours, it’s defensible, and no vendor can argue with it.
Worked example (illustrative — label yours as measured)
A two-person service business, conservative assumptions:
Friday status update: 60 min writing → 10 min reviewing. Saves 50 min. Meeting notes to tasks (3 meetings/week): 45 min → 10 min. Saves 35 min. Monday priority prep: 30 min hunting → 5 min reading the briefing. Saves 25 min. Total: ~110 minutes a week — just under two hours, from three workflows, at a 5-minute review cost each. Scale the workflow count and the number follows linearly; the review cost is what keeps it honest.
These are illustrative placeholders to show the shape of the math. The article they belong to gets updated the moment real measured numbers land — a claim with a timestamp beats a claim with adjectives.
What eats the savings (watch these)
Setup week: the connector and first workflows cost an hour or two. Amortized by week three. Review creep: if reviewing takes longer than 10 minutes per workflow, the workflow needs a tighter prompt, not more of your time. Tool sprawl: five half-adopted workflows save less than two fully trusted ones. Start with one.
Frequently asked questions
How much time can Claude plus Notion save each week?
It depends which recurring workflows you hand over, but the honest way to find out: time three weekly Notion tasks done manually, then time the review-and-approve pass with Claude + Notion MCP doing them. A conservative illustrative example across status updates, meeting notes, and Monday prep comes to roughly two hours a week — substitute your own measured numbers and the method holds.
How do I measure time saved by AI tools without lying to myself?
Measure the same task both ways for one week each: manual time vs. review time with the AI doing the work. Count only the review pass in the AI column — the doing is the machine’s now. One week of honest timing beats a year of vendor benchmarks.
Does the time savings compound?
Yes, but through workflow count, not magic. Each automated recurring task banks its weekly savings independently. Three workflows at ~35 minutes each is ~105 minutes a week, every week. The compounding is just arithmetic that doesn’t stop.
Direct answer: Anthropic moved Claude Code cloud sessions from research preview to general availability on September 23, 2026. Existing Pro subscribers can claim a one-time $100 credit and Max subscribers a one-time $250 credit — but only for cloud-session usage, and only if you claim by 11:59 PM Pacific on October 7, 2026. Unclaimed credit disappears. Claimed credit that goes unused expires November 4, 2026.
What a cloud session actually is
Claude Code running on Anthropic's machines instead of yours. You hand it a task and a GitHub repository; it keeps working after you close the laptop, lose Wi-Fi, or leave the room. Anthropic's pitch: "Cloud sessions run on Anthropic-hosted infrastructure, so the work keeps going even without your computer running."
The practical differences from a local session:
Your laptop is not the bottleneck. No sleep, no battery, no VPN drop killing a long task.
Isolation. The agent works in a hosted environment, not on your machine's files — which limits blast radius.
Accessible everywhere. Start on desktop, check on mobile.
It draws from credit, not just plan limits. The one-time credit applies automatically when you start a session, and it is separate from your weekly usage limits. Anthropic's framing: "If you hit a limit locally, keep going in the cloud until your credit runs out."
The credit, precisely
Pro
Max
One-time credit
$100
$250
Claim deadline
11:59 PM PT, Oct 7, 2026
11:59 PM PT, Oct 7, 2026
Unused credit expires
11:59 PM PT, Nov 4, 2026
11:59 PM PT, Nov 4, 2026
Eligibility
Individual subscriber active Sept 23, 2026
Individual subscriber active Sept 23, 2026
One credit per account. The credit covers cloud sessions only — not chat, not API calls, not local Claude Code. It applies before your regular plan usage, and once it's gone, cloud sessions count against your normal plan limits. There is no separate charge for the cloud container itself.
What you need: a connected GitHub account, because every cloud session works against a repository. No GitHub, no session, no credit use.
How to claim it
1. Confirm your plan. Pro or Max, individual subscription, active on September 23.
2. Connect GitHub. Required before a cloud session will start.
3. Claim. Open claude.ai/code and use the Claim credit prompt, or run /claim-credit inside the Claude Code CLI.
4. Start a session. From claude.ai/code, the Code tab in the Claude mobile app, the desktop app, or claude --cloud in the terminal. Anthropic also lists Routines as a starting point.
5. Watch the dates. Claim by October 7; spend it by November 4. Last call as of today, October 6: the claim window closes 11:59 PM Pacific tomorrow, October 7, 2026. Claim it now — unclaimed credit disappears.
Team and Enterprise users get cloud-session access through premium seats, but the $100/$250 promotional credit is the Pro/Max subscriber offer — evaluate the feature on its own merits if you're outside the promo.
Under the hood
Anthropic runs cloud sessions on fresh Ubuntu 24.04 virtual machines — roughly 4 vCPUs, 16 GB of RAM, 30 GB of disk, per published reports. Organizations that can't let source code run on a vendor's VMs can route sessions to self-hosted environments instead — a separate path from the consumer credit.
Note the contrast with Remote Control: Remote Control connects a web or mobile interface to a Claude Code session running on *your own computer*, so that machine has to stay awake. Cloud sessions remove the machine entirely.
Should you use it?
Treat the credit as a trial budget. Point it at work that's easy to verify: bug fixes with test coverage, dependency updates, questions about a codebase. Check the branch and the pull request the agent produces before merging anything. Anthropic even describes auto-fix of pull requests directly in the cloud as a feature — still check the diff yourself.
For occasional or non-technical users, be honest with yourself: the credit may go unused, because cloud sessions require a GitHub-connected coding workflow to begin with. That's worth knowing before you count on redeeming the full amount.
Claude Code is Anthropic’s official CLI for Claude — a terminal-based agent you can point at any codebase and have it read, write, test, and ship code. It’s different from the Claude.ai chat interface in one key way: Claude Code can act, not just answer. It reads your actual files, runs your actual commands, and makes changes that stick.
This guide walks you through installation, first run, and the commands that cover 90% of what you’ll do daily.
What Claude Code Is (and Isn’t)
Claude Code is a terminal agent — not a chat website.
Claude Code runs in your terminal. It gives Claude access to your local machine — file system, shell, and any MCP servers you configure — so it can do real engineering work: implement features, fix bugs, write tests, explain unfamiliar codebases, and run multi-step agentic workflows.
It is not a code autocomplete plugin (that’s what GitHub Copilot does). Claude Code is a conversational agent that works at the task level, not the token level. You describe what you want; it figures out the steps and executes them.
Installation
Claude Code requires Node.js 18 or later. Install via npm:
npm install -g @anthropic-ai/claude-code
Verify the install:
claude --version
That’s the only dependency. Claude Code is a Node.js CLI — no Docker, no Python env, no platform-specific setup beyond Node.
First-Run Authentication
The first time you run claude, it walks you through authentication. You have two options:
Option 1: Claude subscription (Pro, Max, Team, Enterprise)
Run claude, select “Login with Claude.ai,” and it opens a browser window to authorize. Your subscription covers Claude Code usage — no separate API billing.
Option 2: Anthropic API key
Set your API key as an environment variable before running:
export ANTHROPIC_API_KEY="sk-ant-..."
claude
Or on Windows:
$env:ANTHROPIC_API_KEY = "sk-ant-..."
claude
API key usage is billed per token at standard API rates. For heavy daily use, a Max subscription ($100–$200/month) is usually more economical than API billing.
Your First Session
Navigate to a project directory and start Claude Code:
cd ~/projects/my-app
claude
Claude Code reads your directory automatically. At the > prompt, describe what you want:
> What does this codebase do? Give me a 3-paragraph overview.
Claude reads the files it needs and responds. No configuration required for basic usage — Claude Code infers context from the directory you’re in.
The 5 Commands You’ll Use Daily
The five commands you’ll use daily.
1. claude — Start an interactive session
claude
Launches the REPL (read-eval-print loop). This is where you spend most of your time. Claude has access to your current directory’s files, can run bash commands, and can call any MCP servers you’ve configured.
Within a session, you can:
Ask questions about the codebase
Request implementations (“add a rate limiter to the auth middleware”)
Have Claude run tests and fix failures
Use /help to see available slash commands
Use /clear to reset context without leaving the session
Press Escape twice to interrupt a running task
2. claude -p "prompt" — One-shot non-interactive mode
claude -p "What are all the API endpoints in this codebase?"
Runs a single prompt and exits. No REPL. Good for scripting, CI pipelines, or quick one-off queries you don’t want to interrupt a workflow for. Output goes to stdout — pipe it wherever you need it.
claude -p "Summarize the changes in the last 10 commits" | pbcopy
3. claude mcp add — Connect an external tool
claude mcp add github -- npx -y @modelcontextprotocol/server-github
Adds an MCP server to your Claude Code configuration. After running this, Claude can call the server’s tools in any session. Common additions:
# File system access (scoped to a directory)
claude mcp add files -- npx -y @modelcontextprotocol/server-filesystem ~/Documents
# GitHub integration
claude mcp add github -- npx -y @modelcontextprotocol/server-github
# Web search
claude mcp add search -- npx -y @modelcontextprotocol/server-brave-search
The GitHub and Brave Search servers need API tokens — set them as environment variables before the server starts, or pass them via the --env flag in the mcp add command.
4. claude -c — Continue the last conversation
claude -c
Resumes your most recent Claude Code conversation, including all prior context. Essential for multi-session work on a feature. If you closed the terminal mid-task, claude -c picks up exactly where you left off.
For a specific prior conversation:
claude --resume SESSION_ID
5. claude --model — Select the model for a session
claude --model claude-opus-4-8
Claude Code defaults to the most capable available model for your plan. You can override this per session. Current options:
claude-fable-5 — Highest capability, complex tasks (2x cost vs Opus 4.8)
claude-opus-4-8 — Default for most work, strong balance of quality and speed
claude-sonnet-4-6 — Faster responses, good for routine tasks
claude-haiku-4-5-20251001 — Fastest, lowest cost, short tasks
Slash Commands Inside a Session
While in a Claude Code session (> prompt), these slash commands are available:
Command
What It Does
/help
Show all available commands
/clear
Clear conversation context (keep the session open)
/compact
Compress prior context to save tokens while preserving essential memory
/cost
Show token usage and estimated cost for the current session
/model
Switch the model mid-session
/review
Request a multi-agent code review of the current branch
/init
Generate a CLAUDE.md file with project context for this repo
/exit
End the session
CLAUDE.md — Project-Level Context
Drop a CLAUDE.md file in your project root and Claude Code reads it automatically at session start. Use it to encode project-specific context Claude shouldn’t have to re-derive every session:
# My Project
## Architecture
- Backend: FastAPI + PostgreSQL
- Frontend: React + TypeScript
- Deployed to: AWS ECS
## Development
- Tests: `pytest tests/`
- Local server: `./scripts/start-dev.sh`
- Database migrations: `alembic upgrade head`
## Rules
- Never modify migration files directly
- All API routes go in `src/routes/`
- Use `httpx` not `requests` for HTTP calls
Generate a starter CLAUDE.md for an existing project with /init.
Permission Modes
Permission modes — decide what the agent may touch.
Claude Code asks for confirmation before running bash commands, creating files, or making other changes — unless you grant it broader permissions. There are three ways to control this:
Default: Claude asks before each tool use that modifies files or runs commands
--dangerously-skip-permissions: Skip all confirmations. Use only in isolated environments (Docker containers, CI). Not for everyday use on your primary machine.
Session-level allowlist: During a session, you can approve individual tools for the rest of the session by selecting “Allow always” when prompted
For most work, the default confirmation behavior is the right trade-off — it keeps you in the loop on changes without requiring you to pre-define a permission policy.
IDE Integration
Claude Code integrates with VS Code and JetBrains IDEs. Install the extension from each marketplace, then launch Claude Code from inside the IDE. This keeps the terminal panel visible alongside your editor without alt-tabbing between windows.
The IDE extensions also add shortcuts for common actions like opening Claude Code in the current file’s directory and running one-shot queries against the selected code.
What’s the difference between Claude Code and Claude.ai?
Claude.ai is the web chat interface — good for questions, document analysis, and writing. Claude Code is a terminal CLI that can access your local files, run commands, and act autonomously on multi-step tasks. Claude.ai can’t modify files on your machine; Claude Code can.
Does Claude Code cost extra on top of my Claude subscription?
No. Claude Pro, Max, Team, and Enterprise subscriptions include Claude Code access. You use the same account. Heavy agentic usage counts toward the plan’s usage limits, but there’s no separate Claude Code fee.
Can Claude Code access the internet?
Not by default. Claude Code’s built-in WebFetch tool can fetch content from a specific URL when you provide it. For live web search, add the Brave Search or similar MCP server. Claude can’t browse freely without explicit tool access.
What does Claude Code do with my code?
Claude Code sends the file contents and context it needs to the Anthropic API for inference. Standard Anthropic API data policies apply — if you’re using an API key, you can configure zero data retention. If you’re using a subscription, default Anthropic retention policies apply. Review Anthropic’s privacy policy for current details.
Is Claude Code open source?
Claude Code itself (the CLI client) is not open source — it’s an Anthropic product. The MCP server ecosystem it connects to includes many open-source servers, and the MCP specification itself is open.
What version of Node.js do I need?
Node.js 18 or later. Run node --version to check. The Long-Term Support (LTS) version is always a safe choice.
Last verified: June 12, 2026. Claude Code is updated frequently — run npm update -g @anthropic-ai/claude-code to stay current.
Model Context Protocol (MCP) is the reason Claude can read your files, query your database, search the web, and push code to GitHub — all from inside a single conversation. Without it, Claude would be limited to whatever you paste in manually. With it, Claude connects to almost any external system.
Quick answer: MCP is an open standard developed by Anthropic that lets AI models securely connect to external tools, data sources, and services through a standard client-server architecture (MCP getting started). You install an MCP server for the system you want Claude to access. Claude becomes a client that calls that server. The server executes the action and returns results.
The Problem MCP Solves
The problem MCP solves: one protocol, many tools.
Before MCP, connecting an AI model to external data meant one of two things: either the AI company built a native integration (slow, expensive, proprietary), or you cobbled together a pipeline that passed data manually between systems.
Neither approach scales. If Claude natively supported every database, every API, every file format, and every SaaS tool on the planet, the model would be perpetually behind. And manual copy-paste workflows aren’t agentic — they require you to do all the coordination work the AI should be doing.
MCP solves this with a universal adapter layer. Instead of building individual integrations, Anthropic defined a standard. Now any developer can build an MCP server for any system, and any MCP-compatible AI client (like Claude) can use it automatically.
How MCP Works
How MCP works as a layer between tools and agents.
MCP uses a client-server model over two transport mechanisms:
stdio: The MCP server runs as a local subprocess on your machine. Claude Code spawns it, communicates via standard input/output. This is the most common setup.
HTTP/SSE: The MCP server runs as a network service. Claude connects over HTTP with Server-Sent Events for streaming. Better for remote or shared servers.
The communication protocol underneath is JSON-RPC 2.0 — a lightweight, well-understood standard for calling methods and getting results.
Each MCP server exposes one or more of three primitives:
Tools: Functions Claude can call. Example: read_file(path), create_issue(title, body), run_query(sql). Claude decides when to call them based on context.
Resources: Data sources Claude can read. Example: the contents of a directory, a database schema, a project’s README. Resources are passive — they don’t take actions, they expose information.
Prompts: Reusable prompt templates that servers can provide to standardize how Claude interacts with them.
When Claude sees a task that could benefit from an available tool, it calls the tool, receives the result, and incorporates it into the response. This happens automatically — you don’t have to tell Claude when to use MCP. Claude decides based on what the server exposes.
MCP in Claude Code vs Claude Desktop
Both Claude Code (the CLI tool) and Claude Desktop support MCP, but they configure servers differently.
Claude Code
Claude Code has built-in MCP management via the claude mcp command family:
claude mcp add my-server -- npx -y @modelcontextprotocol/server-filesystem /path/to/directory
claude mcp list
claude mcp remove my-server
Servers added with claude mcp add are stored in your Claude Code config (~/.claude.json or the project-level .claude/settings.json). Project-level configs let you commit MCP server setups to source control so the whole team gets them automatically.
Claude Code also ships with a set of built-in tools that behave like MCP servers but don’t require separate installation: file read/write/edit, bash execution, glob search, grep, web fetch, and the agent spawning tools you’re reading about in this article.
Claude Desktop
Claude Desktop reads MCP server configuration from a JSON file:
Restart Claude Desktop after editing the config. Each server you add appears in the Claude Desktop interface with a hammer icon, and Claude can access its tools in any conversation.
The Most Useful MCP Servers
Anthropic maintains a reference set of official MCP servers. These are the ones worth knowing:
Server
What It Does
Package
Filesystem
Read/write files and directories on your local machine
@modelcontextprotocol/server-filesystem
GitHub
Read repos, create issues, open PRs, push code
@modelcontextprotocol/server-github
PostgreSQL
Read-only SQL queries against a Postgres database
@modelcontextprotocol/server-postgres
SQLite
Read/write a local SQLite database file
@modelcontextprotocol/server-sqlite
Brave Search
Live web search via Brave’s Search API
@modelcontextprotocol/server-brave-search
Puppeteer
Headless browser — screenshot pages, scrape, fill forms
Persistent key-value knowledge graph across conversations
@modelcontextprotocol/server-memory
Beyond the official set, hundreds of community-built MCP servers cover everything from Notion and Linear to AWS and Docker. The MCP ecosystem grew faster than almost anyone expected after the November 2024 launch.
Installing Your First MCP Server
The fastest path is Claude Code with the filesystem server. This gives Claude read/write access to a directory you specify — useful for any project work.
Prerequisites: Node.js installed (the server runs via npx).
In your terminal:
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/Documents/projects
That’s it. Open a Claude Code session. Claude can now list, read, write, and search files inside ~/Documents/projects. Try: “List all Python files in this directory and summarize what each one does.”
For Claude Desktop, edit the claude_desktop_config.json file directly (see format above), then restart the app.
What MCP Cannot Do
What MCP cannot do — permissions and review still matter.
A few things worth understanding before you build on MCP:
MCP servers don’t persist between conversations. Each Claude session starts fresh. If you need state persistence, you need a server with its own storage layer (the Memory server handles this specifically).
MCP doesn’t bypass Claude’s safety guidelines. Claude still decides whether to execute a tool call based on safety and ethics reasoning. Connecting a filesystem server doesn’t give Claude unlimited license to delete files — Claude will still confirm before destructive operations.
Subprocess MCP servers are local. The stdio transport runs servers on your machine. This means they only work when you’re running Claude Code locally. For remote or team-shared access, you need HTTP/SSE transport with a hosted server.
Security Considerations
MCP servers have real permissions. The filesystem server can read and write files. The GitHub server can push code to your repos. The Postgres server can run SQL queries.
Apply the principle of least privilege:
Scope filesystem servers to the directory you actually need, not /
Use read-only database credentials where you don’t need writes
Create GitHub tokens with minimum required scope (e.g., repo for private repos, not org-level admin)
Never commit environment variables containing API keys to source control, even in .claude/settings.json — use env var references instead
MCP servers run with the permissions of the user running Claude. If something goes wrong with a tool call, it can have real consequences. The upside: everything runs locally and through your own credentials — there’s no MCP cloud intermediary with access to your data.
MCP and Claude Code’s Agentic Workflows
The full power of MCP shows up in Claude Code’s multi-step agentic mode. When Claude Code has access to git, a filesystem, a browser, and a search tool simultaneously, it can execute workflows like:
Search the web for a library’s current API (Brave Search)
Read your existing code to understand the integration point (filesystem)
Write the updated code (filesystem write)
Run tests (bash)
Create a PR (GitHub)
Each of these steps would require a separate tool in a traditional automation stack. With MCP, Claude orchestrates all of them within a single session, using whatever servers are available.
This is what makes MCP the infrastructure layer for agentic AI — not a feature, but the foundation that makes complex AI-driven workflows possible.
What does MCP stand for?
Model Context Protocol. It’s an open standard for connecting AI models to external tools, data sources, and services through a standard client-server interface.
Who created MCP?
Anthropic created MCP and released it as an open standard in November 2024. The specification and reference servers are open-source on GitHub. While Claude is the primary client, other AI systems can implement MCP clients too.
Do I need to install MCP to use Claude?
No. Claude works without any MCP servers. MCP is an extension layer — you add servers when you want Claude to access specific external systems. Claude Code also ships with a set of built-in tools (file operations, bash, web fetch) that don’t require MCP installation.
Is MCP available on Claude.ai (the web app)?
MCP server support is primarily in Claude Desktop and Claude Code. The Claude.ai web interface has its own tool integrations (web search, document analysis) but doesn’t support custom MCP servers in the same way.
What’s the difference between MCP tools and Claude’s native tools in Claude Code?
Claude Code’s native tools (Read, Write, Bash, Glob, Grep, WebFetch, Agent) are built into the application and don’t require a separate server process. MCP servers are external — they run as subprocesses or network services that Claude Code connects to. Both expose tools that Claude can call; the mechanism for loading them is different.
How do I build my own MCP server?
Anthropic provides official SDKs for building MCP servers in TypeScript, Python, Go, and other languages. The TypeScript SDK (@modelcontextprotocol/sdk) is the most mature. Start with Anthropic’s MCP documentation and the reference server implementations on GitHub as templates.
Last verified: June 12, 2026. MCP specification and server ecosystem evolve quickly — check the official Anthropic MCP documentation for the current spec.
The most useful thing you can wire into Claude Code isn’t a new model or a clever prompt — it’s your actual database. When Claude Code can read your schema, it stops guessing at table names, column types, and relationships. It starts writing queries that work the first time.
This is the practical walkthrough for connecting Claude Code to a Postgres database via MCP: the command, the credential setup, the safety pattern, and what the workflow actually looks like once it’s running.
Last refreshed: October 8, 2026 (Pacific)
What the Postgres MCP server does
What the Postgres MCP server does.
The official @modelcontextprotocol/server-postgres package (maintained in the MCP reference implementations repo) gives Claude Code four tools: schema inspection, query execution inside a read-only transaction, table detail lookup, and relationship traversal. The server cannot write data — it’s read-only by design in the reference implementation, though third-party variants like postgres-mcp-pro add configurable write access if you need it.
For the majority of development workflows — debugging, writing migrations, generating queries — read-only is exactly what you want. Claude Code can see the shape of your data without being able to touch it.
The fastest path: single command setup
Fastest path — single command setup.
If you just want it running against a local database:
claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres "postgresql://USER:PASSWORD@localhost:5432/mydb"
The -y flag on npx auto-accepts the package install so the command doesn’t hang on first run. Verify with:
claude mcp list
You should see postgres with a connected status. That’s it — Claude Code now has schema access in the current project.
Don’t do this for a production database. The connection string above is hardcoded. It goes into ~/.claude.json as plaintext. Use a dedicated local or staging database during development, and use env vars for anything that matters.
The right way: env vars and a read-only user
Right way — env vars and a read-only user.
Two things to do before connecting to any real database:
1. Create a read-only Postgres user:
CREATE USER claude_readonly WITH PASSWORD 'your-password-here';
GRANT CONNECT ON DATABASE your_db TO claude_readonly;
GRANT USAGE ON SCHEMA public TO claude_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO claude_readonly;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO claude_readonly;
This user can see everything in public and do nothing else. If something goes wrong — a rogue tool call, a compromised session — blast radius is zero.
2. Reference the connection string via env var in .mcp.json:
Set DATABASE_URL in your shell environment or in a .env file (not committed). Add .mcp.json to the repo — everyone on the team gets the same server config — but the actual connection string lives in each developer’s local environment. This is the same pattern you already use for application config. It’s the right pattern here too.
Add the server at project scope so it’s committed:
claude mcp add --scope project --transport stdio db -- npx -y @modelcontextprotocol/server-postgres
Then edit .mcp.json to replace the hardcoded connection string with the ${DATABASE_URL} env var reference shown above.
What Claude Code can actually do with schema access
Once the server is connected, the workflow changes significantly. A few real examples:
Schema exploration: Ask Claude Code “what tables are in this database and how are they related?” and it traverses foreign keys, describes join paths, and builds a mental model of your data layer. No more copy-pasting \dt output.
Query generation: “Write a query that finds users who signed up in the last 30 days but haven’t completed onboarding” produces accurate SQL because Claude Code knows your actual column names. With a generic prompt and no schema access, you’d get plausible-looking SQL that fails because user_status is actually onboarding_state.
Migration drafting: “I need to add a last_login_at column to users — show me the migration and check for existing timestamp patterns in the schema.” Claude Code inspects the schema first, matches your existing column naming conventions, and produces a migration that fits your codebase.
Debugging: “This query is returning the wrong count — here’s the query, check it against the schema.” Claude Code can spot that you’re joining on a nullable column, missing a filter on a soft-delete flag, or aggregating before filtering.
Neon and cloud Postgres
If you’re on Neon, there’s a first-party MCP server with additional capabilities: branch management, database creation, and schema migrations via Neon’s branching model. Set it up with:
npx neonctl mcp add
This runs OAuth through your browser and configures Claude Code automatically. The Neon MCP server is intended for local development and IDE workflows — not production automation — same caution applies.
Debugging when it doesn’t connect
Three commands for when the server shows as disconnected:
claude mcp list # check registered servers and status
claude mcp test db # test a specific server
claude --debug # tail logs including MCP stderr output
Most connection failures are either a wrong connection string, a missing env var, or Node version issues with npx. The debug log shows the exact error from the server process — read it before assuming the problem is Claude Code.
The practical baseline
Five minutes to set up. The productivity delta on any codebase larger than a few tables is immediate — Claude Code stops making column-name mistakes and starts being genuinely useful for data-layer work. Wire up the read-only user, commit the .mcp.json, and add DATABASE_URL to your team’s .env.example. Done.
The model doing the work in a typical Claude Code session is claude-sonnet-5-5 (workhorse) — it handles schema-aware query generation well without burning through Opus 5.5 credits on every lookup.
How do I connect Claude Code to a Postgres database via MCP?
Run: claude mcp add postgres — npx -y @modelcontextprotocol/server-postgres “postgresql://USER:PASSWORD@localhost:5432/mydb”. The -y flag auto-accepts the package install so the command doesn’t hang. Then run claude mcp list and confirm postgres shows a connected status. Use a local or staging database for this quick path, not production.
Is the Postgres MCP server read-only?
Yes. The official @modelcontextprotocol/server-postgres package is read-only by design — it exposes schema inspection, query execution inside a read-only transaction, table detail lookup, and relationship traversal. It cannot write data. Third-party variants like postgres-mcp-pro add configurable write access if you need it.
What’s the safe way to connect Claude Code to a production database?
Create a dedicated read-only Postgres user (GRANT SELECT only), and reference the connection string through an environment variable in .mcp.json using ${DATABASE_URL} rather than hardcoding it. Commit .mcp.json so the team shares the server config, but keep the actual connection string in each developer’s local .env. If a session is ever compromised, the blast radius is zero.
Why does schema access make Claude Code more accurate?
With schema access, Claude Code reads your real table names, column types, and relationships, so it writes queries that work the first time instead of guessing. Without it, you get plausible-looking SQL that fails because user_status is actually onboarding_state. It also improves migration drafting and query debugging by matching your existing conventions.
How do I debug a Postgres MCP server that won’t connect?
Use three commands: claude mcp list to check registered servers and status, claude mcp test db to test a specific server, and claude –debug to tail logs including MCP stderr. Most failures are a wrong connection string, a missing env var, or a Node version issue with npx — the debug log shows the exact server error.
Both Claude Code and OpenAI Codex CLI are terminal-native coding agents: you run them inside a repo, they read your files, edit code, run commands, and iterate. I run both daily on real projects. This is the head-to-head I wish existed when I was deciding which one to make my default. No benchmarks-chasing, just install commands, config files, pricing math, and where each one actually earns its keep. For the broader toolchain these slot into, see our AI operator’s stack.
Claude Code vs Codex CLI: the short answer
Claude Code vs Codex CLI — the short answer.
If you want one sentence: Claude Code is the more mature agentic harness (subagents, hooks, skills, deep MCP, a flat-rate plan that makes heavy use affordable), while Codex CLI is the leaner, cheaper-per-token option with strong raw coding from the GPT-5.x line and a tight sandbox model. Most teams that live in the terminal all day end up on Claude Code for the workflow tooling; people who want a fast, low-cost agent on top of an existing OpenAI subscription reach for Codex.
The honest version: they are closer than tribal arguments suggest. The deciding factors are almost never “which model is smarter this week” and almost always pricing structure, sandbox defaults, and how much workflow scaffolding you need.
How do you install each one?
How do you install each one?
Claude Code installs from npm and runs as the claude command:
npm install -g @anthropic-ai/claude-code
cd your-project
claude
First run walks you through OAuth login (Pro/Max plan) or an ANTHROPIC_API_KEY. On Windows it runs natively in PowerShell now, though a lot of operators still prefer it under WSL for fewer path headaches.
Codex CLI ships an install script and is also on npm:
# Mac / Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
# or via npm
npm install -g @openai/codex
Then codex in your repo. Auth is either a ChatGPT login (Plus/Pro/Business) or an OpenAI API key via codex login. Both tools are open-source clients hitting hosted models, so the install is the easy part; the model access is what you are really buying.
Which models do they run in 2026?
Claude Code defaults to the current Claude flagship. As of June 2026 that is Opus 4.8 (legacy — still listed) for the hardest reasoning, with Sonnet 4.6 (legacy — still listed) as the fast everyday workhorse and Haiku 4
Lineup currency (Sept 2026): Current API list (Sept 2026, verified): Sonnet 5 $2/$10, Opus 5.5 $4/$20, Haiku 4.5 $1/$5, Fable 5.1 $10/$50. Legacy (still listed on Anthropic’s card): Opus 4.8 $5/$25, Sonnet 4.6 $3/$15.
.5 for cheap, high-volume calls. You switch in-session with /model. Opus 4.8 also exposes reasoning-effort levels (high is the default; xhigh and max push deeper on gnarly problems at higher token cost).
Codex CLI runs the GPT-5.x coding line. GPT-5.5 is the current recommended default for complex coding and agentic work, GPT-5.4-mini is the faster/cheaper option for light tasks and subagents, and GPT-5.3-Codex remains a strong coding-tuned choice. Pick the model with codex -m gpt-5.5 or set it in your config.
Practical read: on a clean, well-specified function both produce good code. The gap shows up on long, multi-file refactors where the agent has to hold a lot of context and recover from its own mistakes. That is a harness problem as much as a model problem, which is the next section.
What about workflow features: subagents, hooks, and config?
This is where Claude Code is currently ahead, and it is the real reason it tends to win for power users.
Subagents – Claude Code spawns isolated sub-sessions with their own context window, tool restrictions, and prompts. Great for “go research this in parallel while the main thread keeps coding.” Codex has a lighter subagent concept (often pointed at GPT-5.4-mini to keep cost down) but it is less fleshed out.
Hooks – Claude Code fires deterministic scripts at lifecycle points (PreToolUse, UserPromptSubmit, and more). These run real code, so they cannot hallucinate: you can hard-block a dangerous command, auto-format on every edit, or inject context before the model sees a prompt. Codex leans on its approval/sandbox policy and execpolicy rules instead of a general hook system.
Skills and slash commands – In Claude Code, custom slash commands have merged into skills; /your-command still works and skills add reusable, packaged capabilities. Codex uses prompt files and profiles rather than a skills layer.
Project memory – Both read a project instruction file. Claude Code uses CLAUDE.md; Codex uses AGENTS.md (checked in a fallback order including AGENTS.override.md and .agents.md). Keep these tight: architecture, conventions, and the few rules the agent keeps forgetting.
Codex’s config story is clean if you like a single file: ~/.codex/config.toml holds your model, approval policy, sandbox mode, MCP servers, and named profiles you switch with codex --profile work. Claude Code spreads config across ~/.claude/ and .claude/settings.json plus per-project files, which is more surface area but more granular control.
How do the sandbox and approval models compare?
This matters more than most comparisons admit, because it governs how much the agent can do without asking.
Codex CLI has an explicit, well-documented sandbox. Sandbox modes run from read-only to workspace-write (edit files in the project, network off by default) up to full access, paired with approval policies like untrusted and on-request. On Windows the native sandbox can run unelevated or elevated. The mental model is clear: pick how much rope, then approve escalations.
Claude Code manages permissions through allow/deny rules and modes (including a plan mode that reasons without touching files, and an auto-accept mode for trusted loops). Combined with PreToolUse hooks you can build a strict policy, but it is more “assemble it yourself” than Codex’s preset sandbox tiers.
If you are dropping an agent onto an unfamiliar or sensitive repo, start read-only in both. Codex makes that posture a one-flag default; Claude Code gives you finer-grained control once you invest in the config.
Do both support MCP?
Do both support MCP?
Yes, and this is a genuine tie that matters. Both speak the Model Context Protocol, so you can wire in the same external tools, databases, and APIs. Codex registers STDIO or streaming-HTTP MCP servers in ~/.codex/config.toml and launches them at session start. Claude Code adds servers via claude mcp add or JSON config. If you have already built MCP integrations, neither tool locks you out. New to MCP, start with our Claude MCP setup guide and the Notion MCP setup walkthrough.
What does each one cost?
Pricing is where the decision often gets made, so here are the real numbers as of June 2026.
Claude Code plans:
Pro – $20/mo: Sonnet 4.6 plus some Opus, roughly enough for focused daily sessions, not all-day heavy use.
Max 5x – $100/mo: much larger windows, real Opus headroom.
Max 20x – $200/mo: the heavy-user tier; effectively flat-rate firehose access.
API pay-as-you-go: Opus 4.7 about $5/$15 per million input/output… (legacy (still listed) Opus tier runs higher), Sonnet 4.6 (legacy — still listed) $3/$15, Haiku 4.5 $1/$5.
Codex CLI: Included in ChatGPT Plus/Pro/Business plans (usage g
Lineup currency (Sept 2026): Current API list (Sept 2026, verified): Sonnet 5 $2/$10, Opus 5.5 $4/$20, Haiku 4.5 $1/$5, Fable 5.1 $10/$50. Legacy (still listed on Anthropic’s card): Opus 4.8 $5/$25, Sonnet 4.6 $3/$15.
Codex CLI: Included in ChatGPT Plus/Pro/Business plans (usage governed by your plan’s limits), or pay-as-you-go on the API. GPT-5.3-Codex runs about $1.75 per million input / $14 per million output, with cheaper input on cached tokens. The mini model is far cheaper for light work.
The structural difference: Claude Code’s Max plans are flat-rate, which is why heavy users love them. People have tracked billions of tokens that would cost five figures on API metering but ran around a few hundred dollars on Max. Codex’s per-token rates are lower per unit and great if your usage is bursty or already bundled into a ChatGPT subscription, but a true all-day agent habit can run up metered cost faster than a flat plan. Estimate your monthly token volume honestly, then do the arithmetic both ways.
So which coding agent should you actually use?
Pick Claude Code if you want the deepest agentic workflow (subagents, hooks, skills), you are a heavy daily user who benefits from the flat-rate Max plan, or you need fine-grained, scriptable control over what the agent can do. It is the more complete operator’s harness in 2026.
Pick Codex CLI if you want lower per-token cost, you already pay for ChatGPT and want to use that allowance, you like the clean preset sandbox/approval model, or you simply prefer the GPT-5.x output style. It is lean, fast to stand up, and genuinely capable.
The move a lot of us make: run both. They are cheap relative to engineer time, they share MCP servers, and they have different failure modes. When one gets stuck in a loop on a hard bug, handing the same task to the other with fresh context often breaks the logjam. If you are weighing terminal agents against IDE-native ones, our Claude Code vs Cursor breakdown covers that axis.
Is Claude Code or Codex CLI better for large refactors?
Claude Code tends to hold up better on long multi-file refactors, mostly because of subagents and hooks that keep context organized and catch mistakes deterministically. Codex can do it too, especially with GPT-5.5, but you lean harder on tight AGENTS.md instructions and approval gates.
Can I use Codex CLI without a ChatGPT subscription?
Yes. Run codex login with an OpenAI API key and you pay per token instead of through a ChatGPT plan. Same for Claude Code with an ANTHROPIC_API_KEY if you would rather meter than subscribe.
Do they work on Windows natively?
Both do in 2026. Claude Code runs in PowerShell (many operators still prefer WSL for cleaner paths), and Codex CLI has a native Windows installer plus a Windows sandbox with unelevated/elevated modes. Watch out for shells that mangle /tmp or C: style paths in arguments.
What is the single biggest difference?
Pricing structure and workflow depth. Claude Code offers flat-rate Max plans and a richer harness (subagents, hooks, skills); Codex offers lower per-token rates and a cleaner preset sandbox. Model quality is close enough that those two factors usually decide it.
Which model do they run by default?
Claude Code defaults to the legacy (still listed) Claude flagship (Opus 4.8 (legacy — still listed) as of June 2026, with Sonnet 4.6 (legacy — still listed) for everyday speed). Codex CLI recommends GPT-5.5 for complex work, with GPT-5.4-mini and GPT-5.3-Codex as alternatives
Lineup currency (Sept 2026): Current API list (Sept 2026, verified): Sonnet 5 $2/$10, Opus 5.5 $4/$20, Haiku 4.5 $1/$5, Fable 5.1 $10/$50. Legacy (still listed on Anthropic’s card): Opus 4.8 $5/$25, Sonnet 4.6 $3/$15.
. Switch in-session with /model or the -m flag.
How do I get either tool cited or surfaced by AI engines for my own docs?
That is a content question, not a tooling one. The same structure that makes this page answerable, short factual answers, question-shaped headers, and a visible FAQ, is what AI engines reward. See how AI engines cite content for the full playbook.
Claude Code and Cursor are the two tools most working developers actually reach for in 2026, and they are not the same kind of thing. Cursor is an AI-native code editor (a VS Code fork) where the model lives inside your IDE. Claude Code is a terminal agent that lives in your shell and edits files, runs commands, and drives git from the command line. This is the honest version: what each one is good at, what they cost right now, and a simple rule for picking.
Claude Code vs Cursor: what is the actual difference?
Claude Code vs Cursor — what is the actual difference?
The short answer: Cursor is an editor you type in; Claude Code is an agent you delegate to. Cursor keeps you in the driver’s seat with autocomplete, inline edits, and a chat sidebar that sees your open files. Claude Code takes a goal and works the repo autonomously in the terminal, asking permission before it touches things.
Dimension
Claude Code
Cursor
Form factor
Terminal CLI (plus IDE extension, web, desktop)
Full IDE (VS Code fork)
Primary loop
Delegate a task, approve actions
Type code, accept suggestions
Models
Claude only
Multi-model: Grok included on higher tiers; Claude/GPT/Gemini at API list on Premium+
Tight edit loops, autocomplete, staying in one window
Entry price
$20/mo (Pro) or $17 annual
Free limited / Plus $8 (Grok only) / Premium $30
Billing model
Usage windows (5-hour + weekly)
Shared AI usage pool; third-party models at API list on Premium and above
How does each one actually work?
How each one actually works.
Claude Code (terminal agent)
You install it and run it from inside a project directory. Official claude.com copy: Claude Code is included in all paid Claude plans and shares the same usage pool as chat.
npm install -g @anthropic-ai/claude-code
cd my-project
claude
From there you talk to it in plain language. It reads files, proposes edits as diffs, and runs shell commands only after you approve them. Drop a CLAUDE.md in the repo root. Headless mode: claude -p "...".
Cursor (AI IDE)
Cursor is a download. Tab completion, inline edit, agent mode, and a model picker. Official cursor.com/pricing (checked October 13, 2026) lists Free, Plus $8/mo (Grok models only), Premium $30/mo (4x Plus; third-party models at API list price), Super $100/mo (15x), Ultra $200/mo (50x), Teams from $30+/user. Docs at cursor.com/docs/models-and-pricing still reference older Pro $20 / Pro+ $60 / Ultra $200 pools. Quote both; do not average.
What does Claude Code cost in 2026?
As of October 13, 2026, official claude.com / platform.claude.com:
Pro: $20/month, or $17/month billed annually ($200 up front). Includes Claude Code.
Max 5x: $100/month. 5x Pro usage. Includes $100/month API credits.
Max 20x: $200/month. 20x Pro usage. Includes $200/month API credits.
API: Haiku 5.5 $0.10 / $0.50 per MTok under 100k prompt tokens ($0.50 / $2.50 over); Sonnet 5.5 $2 / $10 with cache reads $0.10; Opus 5.5 $4 / $20 (cache read $0.20); Fable 5.1 $10 / $50 (cache read $0.25). Batch 50% off. US-only inference 1.1x on Claude 4.6+.
There is a 5-hour rolling session window plus weekly limits on paid plans. Chat and Claude Code draw from one pool. Confirm in Settings > Usage.
What does Cursor cost in 2026?
Free: Limited.
Plus: $8/month. Grok models only.
Premium: $30/month. 4x Plus usage. Third-party models (Claude, GPT, Gemini) at API list price.
Super: $100/month. 15x Plus.
Ultra: $200/month. 50x Plus. Earliest access.
Teams: From $30+/user/month.
On the live pricing page, third-party model usage is not included in the monthly price and is billed separately at API list. Docs still describe older Pro/Pro+/Ultra usage pools for Cursor Models vs Other Models. Existing subscribers may keep prior plans.
Which models do you actually get?
Claude Code is Claude-only.
Cursor includes Grok on Plus and above; Premium and higher add third-party models at API list price.
Which one is better for big refactors and automation?
Claude Code for repo-wide delegate work and headless claude -p runs. Cursor agent is strong inside the IDE; it is not a cron target.
Which one is better for everyday coding flow?
Cursor for most people who want tab completion and one window, especially if Grok covers the loop.
Can you use both together?
Yes. Common setup: Cursor as the editor, Claude Code in the integrated terminal. Claude Pro is $20; Cursor Premium is $30 if you need Claude models inside Cursor at API rates.
Bottom line
Pick Claude Code if you want an autonomous terminal agent and you are happy with Claude as your one model. Entry is Pro at $20/$17.
Pick Cursor if you want autocomplete, Grok included, and a model picker. Entry for third-party is Premium at $30 plus API list.
Pick both if the seats are cheaper than the hours you lose switching contexts.
FAQ
Is Claude Code or Cursor cheaper?
Claude Code starts at Pro $20/mo ($17 annual). Cursor Free is limited; Plus is $8 (Grok only); Premium is $30 with third-party models billed at API list on top. Claude Code meters by 5-hour plus weekly windows. Cursor meters a shared pool then on-demand / API list.
Does Cursor use Claude?
Yes, on Premium and above, at API list price (not included in the seat). You do not need a Claude Pro seat to use Claude models inside Cursor, but you pay the list rate for them.
There are two ways to connect Notion to Claude over the Model Context Protocol (MCP), and almost every tutorial only covers one of them. Worse, none of them tell you why the connection succeeds but Claude still says it cannot find any of your pages. This guide covers both paths – the hosted OAuth connector and the self-hosted token route – with the exact config, the scopes that matter, the rate limit you will hit, and the specific error strings that show up when something is wrong. It is written from actually running this, not from reading the docs.
Which Notion MCP should you use: hosted or self-hosted?
Hosted vs self-hosted Notion MCP.
Short answer: use the hosted MCP at https://mcp.notion.com/mcp for almost everything. It uses OAuth, so you never handle a token, and it respects your existing Notion permissions automatically. Use the self-hosted npm server with an internal integration token only when you need headless, unattended automation (a cron job, a server with no human to click “Allow”), because the hosted server requires an interactive OAuth approval that a background process cannot complete.
Factor
Hosted (mcp.notion.com)
Self-hosted (npm + token)
Auth
OAuth (interactive)
Internal integration token (ntn_)
Permissions
Inherits your full Notion access
Only pages you explicitly share
Setup time
~2 minutes
~10 minutes
Headless / cron
No (needs a human to approve)
Yes
Best for
Claude Desktop, Claude Code, daily use
Servers, scripts, multi-user backends
Notion MCP config generator
Answer two questions, get your exact setup. No guessing, no stale docs.
Copied!
Rolling this out across a team? One person’s MCP setup is a weekend project. Ten people’s is an IT ticket queue. We set up AI workflows for businesses — Notion, Claude, and the glue between them. Tell us what you’re connecting →
How do I connect Notion to Claude using the hosted MCP?
Connect Notion to Claude via hosted MCP.
This is the fast path. No token, no npm.
Claude Desktop / Claude.ai: Open Settings > Connectors, click Add custom connector (or pick Notion if it appears in the directory), and paste the URL https://mcp.notion.com/mcp. A Notion OAuth window opens. Approve it, choose which workspace and which top-level pages the connector may see, and you are done. The scope you pick in that OAuth screen is the whole ballgame – see the gotcha below.
Claude Code (CLI): one command.
claude mcp add --transport http notion https://mcp.notion.com/mcp
Then run /mcp inside Claude Code to trigger the OAuth login. After approving, verify it is live:
claude mcp list
You should see notion with a connected status. If it shows failed or needs auth, run /mcp again and complete the browser flow – the CLI cannot proceed past OAuth on its own.
How do I set up the self-hosted Notion MCP with an integration token?
Use this when you need automation that runs without a human. Three steps: create the integration, get the token, then wire it into your MCP config.
1. Create the integration and copy the token
Go to https://www.notion.so/my-integrations and click New integration. You must be a Workspace Owner – if the button is greyed out, that is why.
Name it, select the workspace, and choose Internal integration type.
On the integration’s settings page, set Capabilities: Read content, plus Update/Insert content if you want Claude to write. If you only grant Read, every write attempt fails with a permission error later – this is a common self-inflicted wound.
Click Show, then copy the Internal Integration Token. New tokens start with ntn_ (older ones start with secret_ and still work). Treat it like a password.
2. Add it to your MCP config
For Claude Desktop, edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/; Windows: %APPDATA%\\Claude\\). Add:
Restart Claude Desktop completely (quit, do not just close the window). On Windows, if npx is not found, use the full path to npx.cmd or run via cmd /c – the config does not inherit your shell PATH.
3. The step everyone forgets: share the pages
An internal integration starts with access to nothing. Creating it and pasting the token is not enough. For every page or database you want Claude to touch, open it in Notion, click the … menu (top right), choose Connections (or Add connections), and select your integration. Access is inherited by child pages, so sharing a top-level page covers its whole subtree. Skip this and Claude will connect cleanly and then truthfully report that it cannot see any content.
What are the most common Notion MCP errors and how do I fix them?
Common Notion MCP errors and fixes.
These are the failure messages you will actually see, and what each one means.
“Could not find page” / Claude returns zero results from a workspace that clearly has pages
Cause, in order of likelihood: (1) you did not share the page with the integration (self-hosted), or you scoped the OAuth grant too narrowly (hosted); (2) the page is in a different workspace than the one the integration is tied to. Fix: re-check the Connections menu on the specific page, or re-run the OAuth flow and widen the page selection. An integration token is bound to one workspace – it cannot see another.
API token is invalid (HTTP 401 unauthorized)
The token is wrong, was regenerated, or has a stray space/newline from copy-paste. Re-copy it with the Show button, paste it into the env block with no surrounding whitespace, and restart the client. If you rotated the token in Notion, the old one dies immediately – update every config that used it.
Claude tried to write a property type that does not match the database schema – for example sending plain text into a Select, or a malformed date. This is not a connection problem. Tell Claude the exact property names and types, or ask it to fetch the database schema first before writing.
“Rate limited” / HTTP 429
Notion enforces roughly 3 requests per second per integration (averaged, with short bursts tolerated). Bulk operations – “update 200 rows,” “scan every page” – blow straight through this. The fix is pacing, not a bigger plan: have Claude batch in small groups and add a short delay between calls. If you are scripting around the MCP, honor the Retry-After header on a 429 instead of hammering.
spawn npx ENOENT (server will not start, self-hosted)
Node/npx is not on the PATH the client sees. Install Node, then point command at the absolute path to npx (or npx.cmd on Windows). This is the number-one self-hosted startup failure.
MCP server shows “failed” in claude mcp list right after adding it
For the hosted server this almost always means OAuth was never completed – run /mcp and approve in the browser. For the self-hosted server it means the process crashed on launch; run the npx command manually in a terminal to see the real stack trace.
Notion MCP Configuration Checklist
Run this before you call the setup done. Every box is a real failure mode from the guide above.
Setup completeness 0 of 10
Check each item as you verify it.
All ten green. Your Notion–Claude wiring is solid. Rolling this out across a team, or want it wired into real workflows instead of weekend tinkering?
What can Claude actually do with Notion once connected?
With read + write capabilities granted, Claude can search your workspace, read pages and databases, create pages, append blocks, and update properties on existing rows. Practical things that work well: “summarize this Notion doc,” “create a row in my tasks database with these fields,” “find every page mentioning X and list the links,” “turn this conversation into a meeting-notes page.” Things that get awkward: very large pages (the response can get truncated – verify the write actually landed by fetching it back), and bulk edits that trip the rate limit. A reliable habit is to treat Notion as the source of truth and have Claude verify by re-fetching after any write, because timeouts on big pages can commit silently and still return a malformed response.
What is the connection worth to you?
Operators who wire Claude into Notion typically cut manual capture, entry, and doc-hunting time by roughly 30% — an illustrative estimate, not a guarantee. Put in your own numbers:
Saved per week
1.5 hrs
Saved per year
78 hrs
Value per year
$5,850
Illustrative math: 30% of your manual information-work hours, × 52 weeks. Real savings depend on your workflows.
Security notes from running this in production
Scope the OAuth grant tightly. The hosted connector inherits whatever you approve. If you only need one project area, share only that top-level page, not the whole workspace.
Never hardcode the token in a file you might commit. Keep ntn_ tokens in an env var or your OS secret store, and reference them from config. If a token leaks, revoke it in my-integrations immediately – revocation is instant.
Grant the minimum capability. If Claude only needs to read, do not enable insert/update. You can always widen it later.
Audit which integrations have access to sensitive databases periodically; the Connections menu on each page shows the current list.
If you are wiring up several connectors at once, the mechanics generalize – see our broader Claude MCP setup guide for the config patterns that apply across servers, and the AI operator’s stack for how Notion fits alongside the other tools day to day. If your reason for connecting Notion is to get your own content cited by AI systems, the structure of the pages matters as much as the wiring – see how AI engines cite content.
Frequently Asked Questions
Do I need a paid Notion plan to use the MCP?
No. The API and integrations work on free Notion workspaces. You do need to be a Workspace Owner to create an internal integration.
Why does Claude say it can’t find my Notion pages after connecting?
The most common reason is that you haven’t shared the specific pages or databases with your Notion integration. Notion’s permission model requires explicit page-level grants — a successful connection does not automatically give access to all your content. Go to the page in Notion, click the three-dot menu, choose ‘Add connections’, and select your integration.
What rate limits does the Notion API have?
Notion’s API enforces a rate limit of 3 requests per second per integration. For typical conversational use this is invisible, but if you ask Claude to crawl a large database or process many pages in sequence, you may see 429 errors. The fix is to add a short sleep between bulk operations or use Notion’s pagination to fetch in smaller batches.
What does the ntn_ prefix mean on my token?
It is the current internal integration token format. Tokens created today start with ntn_; older secret_ tokens still function and do not need to be replaced.
Can the hosted Notion MCP run in a headless cron job?
No. The hosted server requires interactive OAuth approval, which an unattended process cannot complete. Use the self-hosted npm server with an ntn_ token for headless automation.
How do I let Claude write to Notion, not just read?
Enable Update content and Insert content under the integration’s Capabilities (self-hosted), or approve write scope during OAuth (hosted). Read-only is the default and will reject every write with a permission error.
Where do I put the Notion MCP config for Claude Desktop?
In claude_desktop_config.json – ~/Library/Application Support/Claude/ on macOS, %APPDATA%\\Claude\\ on Windows. Add a notion entry under mcpServers and fully restart the app.
Can one integration access two workspaces?
No. An internal integration is bound to the single workspace it was created in. For a second workspace, create a second integration (or a second OAuth grant on the hosted connector).
What is the Notion MCP server for Claude?
The Notion MCP server is a connector that lets Claude read, search, and interact with your Notion workspace through the Model Context Protocol. With it connected, you can ask Claude to find pages, summarize databases, draft content into Notion, or retrieve information — all without copying and pasting anything manually.
What is the difference between the Notion OAuth connector and the self-hosted token route?
The OAuth connector (available in Claude Desktop’s built-in integrations) is the fastest path — authorize once and Claude gets read access to pages you share with the integration. The self-hosted route uses a Notion Internal Integration token in your claude_desktop_config.json, giving you more control over scopes and works in Claude Code environments where OAuth connectors aren’t available.
What scopes does the Notion MCP integration need?
For read operations: Read content and Read user information. For write operations: Update content and Insert content. Avoid requesting more scopes than you need — the minimum set reduces the blast radius if a token is ever compromised. Set scopes when creating your Notion Internal Integration at notion.so/my-integrations.
Does the Notion MCP integration work with Claude Code?
Yes. Add it via ‘claude mcp add notion npx @notionhq/notion-mcp-server’ and set your NOTION_API_KEY as an environment variable. Claude Code picks it up on the next session. The self-hosted token route works in both Claude Desktop and Claude Code; the OAuth connector is currently Desktop-only.
What is the Notion MCP server and how do I set it up?
The Notion MCP server is a connector that lets Claude read, search, and write to your Notion workspace through the Model Context Protocol — no copy-pasting between apps. Two setup routes: the hosted route (Claude Desktop → Settings → Connectors → Notion → authorize via OAuth, about two minutes) or the self-hosted route (create a Notion internal integration, copy the token, add it to your MCP config, then share your pages with the integration — the step almost everyone forgets).
How do I connect Claude to Notion?
Use the hosted MCP connector: in Claude Desktop, open Settings → Connectors, choose Notion, and authorize via OAuth. For Claude Code, add Notion’s remote MCP server with the claude mcp add command. After connecting, verify Claude can actually see your pages — if it returns zero results on a workspace that clearly has pages, you skipped the page-sharing step.
Can Claude read and write my Notion databases?
Yes. Reading works as soon as the connection is live — Claude can search pages, query databases, and pull property values. Writing needs the integration to carry write scopes and the target pages shared with it; then Claude can append database rows, update properties, and draft pages directly. Keep the approval habit for shared workspaces: Claude drafts, you approve.