Connecting Business Data to Claude Code

What you'll learn

• claude mcp add connects Postgres and Notion as first-class tools Claude can query, read, and update
• Postgres MCP handles relational data (customers, orders, metrics); Notion MCP handles documents, wikis, and project specs
• Scope servers correctly: user scope for personal data, project scope for team databases, local scope for experiments
• Always use environment variables for connection strings and API tokens; never embed credentials in config files

The problem: your data is invisible to your AI

Claude Code can read every file in your repository, run shell commands, and generate code. It cannot see your production database, your team's Notion wiki, or any system that lives outside the filesystem unless you explicitly connect it. This means every data question (what were last month's top ten customers?) requires you to switch context: leave Claude Code, open a database client, run the query, read the result, and paste it back into the conversation. You become the API layer between your AI and your data.

The Model Context Protocol removes that manual step. An MCP server acts as a bridge: it exposes your database or business tool as a set of callable functions that Claude Code discovers at startup, the same way it discovers your local filesystem. Once connected, you ask Claude "which customers churned in Q2?" and it runs the SQL, interprets the result, and gives you an answer in the same conversation.

This lesson covers two MCP servers that connect to real business systems: Postgres for relational data and Notion for documents and wikis. Choose whichever matches your stack, or configure both.

Options & when to use each

Option	Good for	Costs	When to pick
Postgres MCP (@modelcontextprotocol/server-postgres)	Querying relational data: customer records, sales metrics, inventory, analytics tables. Tables, views, and schemas all exposed as discoverable resources.	Uses a database connection that counts toward your pool limits. Read-write mode means Claude can modify data if you grant it.	You have structured data in a Postgres database and need Claude to query it without you acting as the SQL intermediary.
Notion MCP (@notionhq/notion-mcp-server)	Reading and updating Notion pages, databases, and wikis. Claude can search your workspace, retrieve page content as markdown, and edit pages.	Requires a Notion integration token with page access. Rate limits apply (Notion API tier). Page content retrieval can be slow for large databases.	Your team's specs, project plans, and documentation live in Notion. You want Claude to pull context from those pages before writing code that implements them.
Filesystem MCP (already covered in MCP Servers)	Reading and writing local files, the simplest MCP server. Good for one-off data exports you dump to CSV/JSON and want Claude to analyze.	Manual step: you must export data to a file first. No live connection, no schema awareness.	Quick-and-dirty analysis when you do not need a persistent database connection. This is what the basic MCP lesson covers; skip to the next section if you want live data.

Build it

Part 1: Connect Postgres

The official Postgres MCP server ships from the @modelcontextprotocol org. It connects over a standard Postgres connection string and exposes your tables and views as tools Claude can query.

Step 1: Verify your Postgres connection works.

Before adding the MCP server, confirm you can reach the database from your terminal. The connection string is the same one the MCP server will use.

psql "postgresql://username:password@localhost:5432/mydb" -c "SELECT 1"

If that fails, the MCP server will fail too. Fix your Postgres connection first (check pg_hba.conf, confirm the port, test with pg_isready).

Step 2: Add the MCP server with an environment variable for the connection string.

Never put your database password in a config file or shell command that might end up in your terminal history. Use an environment variable:

export DATABASE_URL="postgresql://username:password@localhost:5432/mydb"

Now register the server. The -s local flag scopes it to your personal project instance:

claude mcp add -s local postgres -- npx -y @modelcontextprotocol/server-postgres "$DATABASE_URL"

What happens: Claude Code writes a postgres entry to .claude/settings.local.json. On every session start, it spawns npx -y @modelcontextprotocol/server-postgres as a child process, passing the connection string. The server connects to Postgres, discovers the schema, and advertises available query tools.

Step 3: Verify it is alive.

claude mcp list

You should see postgres: connected (stdio). If you see an error instead, jump to the "What goes wrong" section below.

Step 4: Query your data.

Start Claude Code and ask a question that requires the database:

> How many rows are in the users table? Show me the schema of the orders table too.

Claude will call query (the tool exposed by the Postgres MCP server) and return the result inline. You can ask for aggregations, joins, schema exploration, and even write queries that the server executes.

Read-write vs. read-only. The Postgres MCP server uses whatever permissions the connection user has. If the user can INSERT, UPDATE, and DELETE, Claude can too. For production data, create a read-only Postgres user and use that connection string. Save the read-write connection for development databases.

Part 2: Connect Notion

Notion's official MCP server (@notionhq/notion-mcp-server) exposes your Notion workspace through the Notion API. Claude can search pages, read content as markdown, and update existing pages.

Step 1: Create a Notion integration and get your token.

1. Go to notion.so/my-integrations.
2. Click "New integration", give it a name (e.g., "Claude Code"), and select the workspace.
3. Copy the "Internal Integration Secret" (it starts with ntn_). This is your API token.
4. Go to any Notion page or database you want Claude to access, click the ... menu in the top right, select "Connections", and add your integration. Without this step, the token is valid but has no access to any content.

Step 2: Store the token as an environment variable.

export NOTION_TOKEN="ntn_your_token_here"

Step 3: Add the MCP server.

claude mcp add -s user notion -- npx -y @notionhq/notion-mcp-server

The NOTION_TOKEN environment variable is all the server needs. It reads it at startup. Scope -s user makes sense for a personal Notion workspace (available in all your projects). Use -s project if the workspace is shared across a team repository.

Step 4: Verify and query.

claude mcp list
# notion: connected (stdio)

Start Claude Code and try:

> Search my Notion for pages about the Q3 product roadmap. Summarize the top three findings.

Claude will call the Notion server's search and page-read tools, retrieve the content, and summarize it. You can also ask Claude to update a Notion page:

> Add today's deployment notes to the Release Log page in Notion. List the three PRs that went out.

Part 3: Using both in one session

Postgres and Notion can run side by side. Register both, then start Claude Code:

claude mcp add -s local postgres -- npx -y @modelcontextprotocol/server-postgres "$DATABASE_URL"
claude mcp add -s user notion -- npx -y @notionhq/notion-mcp-server
claude

Now Claude has access to your database and your documentation in the same session. Ask a question that spans both:

> Look up the top five customers by revenue in Postgres, then search Notion for any account plans or notes mentioning those customers.

This pattern (multiple servers, one session) is the foundation of the next lesson, where we combine servers across different domains (GitHub + Filesystem + Search) for real workflows.

What goes wrong

Mistake	How you notice it	The fix
Connection string has wrong host/port/credentials	claude mcp list shows the server but Claude says it cannot connect, or the query tool returns connection errors	Test the connection string directly: psql "$DATABASE_URL" -c "SELECT 1". Fix whatever that reveals (wrong host, wrong port, firewall, pg_hba.conf). The MCP server gets the same error.
Notion integration not added to a page	Claude reports "no pages found" or "access denied" even though the token is correct	Go to each Notion page or database you want to access and manually add the integration under the Connections menu. Tokens have no access until you explicitly share pages with them.
Scope confusion: server registered in user scope but project expects it	Claude does not list the server you added when you are in your project directory	Check which scope the server lives in: claude mcp list shows scope. Project-scoped servers only load in that project's directory. User-scoped servers load everywhere. Re-add with the correct -s flag.
Read-write Postgres user on production data	Claude runs an UPDATE or DELETE you did not intend	Create a dedicated read-only Postgres user: CREATE USER claude_readonly WITH PASSWORD '...'; GRANT CONNECT ON DATABASE mydb TO claude_readonly; GRANT USAGE ON SCHEMA public TO claude_readonly; GRANT SELECT ON ALL TABLES IN SCHEMA public TO claude_readonly;. Use that user's connection string for the MCP server.
claude mcp add fails with "command not found" for npx	The server starts but immediately exits; claude mcp list shows an error state	Install Node.js if npx is not on your PATH. Most systems: sudo apt install nodejs npm or use nvm. Verify with npx --version.

Confirm it worked

Run this validation sequence to confirm both servers are functioning:

# 1. List all MCP servers. Both should show "connected"
claude mcp list
# Expected: postgres: connected (stdio), notion: connected (stdio)

# 2. Start Claude Code and ask it to query your database
claude -p "Query the Postgres database and tell me what tables exist. List their names and row counts."

# 3. Ask Claude to find something in Notion
claude -p "Search my Notion workspace for any page with 'roadmap' in the title. List the page titles you find."

# 4. Clean up if something went wrong and you need to start over
claude mcp remove postgres
claude mcp remove notion

If step 2 returns a table list, Postgres MCP is working. If step 3 returns page titles, Notion MCP is working. Both working means you are ready for multi-tool workflows.

Next: Multi-Tool MCP Workflows