MCP Setup (Linear & Notion)

Model Context Protocol (MCP) servers enable Claude Code to directly interact with Linear and Notion for automated project management and documentation.

What is MCP?

MCP (Model Context Protocol) allows Claude Code to connect to external services like Linear and Notion, enabling it to:

Create and update Linear tasks automatically
Sync project progress to Notion
Link GitHub commits/PRs to Linear issues
Generate milestone documentation

Linear MCP Setup

Linear is our primary project tracking tool for day-to-day task management. Workspace: https://linear.app/workally/projects/all

Installation
Usage
Automation

Step 1: Get Linear API Key

Access Linear Settings

Go to https://linear.app/workally/settings/api
Sign in with your WorkAlly account

Create API Key

Click “Create new personal API key”
Name: Claude Code MCP
Description: For automated task tracking via Claude Code
Click “Create key”

Copy API Key

Copy the key immediately - it starts with lin_api_You won’t be able to see it again after closing the dialog.

Step 2: Configure Claude Code

Add Linear MCP to your Claude Code configuration file.Config location: ~/.claude/config.toml

[mcp_servers.linear]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-linear"]
env = { LINEAR_API_KEY = "lin_api_YOUR_KEY_HERE" }

Replace lin_api_YOUR_KEY_HERE with your actual API key.

Step 3: Restart Claude Code

# Reload MCP servers
claude --reload-mcp

# Reload VS Code window
# Press: Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows)
# Type: "Reload Window"
# Press Enter

Step 4: Verify Connection

Test the connection by asking Claude Code:

"Check if Linear MCP is connected and list my Linear teams"

Expected response: Claude lists your Linear teams and workspaces.

Creating Projects from plan.md

After creating your brief/plan.md, initialize Linear tracking:

"Read brief/plan.md and create a new Linear project called '[Your Project Name]'.
Create milestones for each phase and convert all tasks to Linear issues with
appropriate labels (phase-0, phase-1, etc.)."

Claude Code will:

Create Linear project
Add milestones (Phase 0, Phase 1, etc.)
Create issues for each task
Add labels and priorities
Set due dates based on phase timing

Daily Progress Updates

Update after completing tasks:

"I just finished implementing user authentication.
Update Linear issue WOR-123 to 'Done' and add completion notes."

End-of-day sync:

"Review plan.md and update Linear with today's progress.
Mark completed tasks as done and add notes to in-progress issues."

Creating New Issues

Bug reports:

"Found a bug in login validation. Create a Linear issue with priority High,
label 'bug', and assign to current sprint."

Feature requests:

"Create a Linear issue for adding Google OAuth with label 'enhancement'
and add it to Phase 2 milestone."

PR & Commit Linking

Link PRs to Linear:

"I just created PR #23 for user authentication.
Update Linear issue WOR-123 with the PR link and move to 'In Review'."

Commit message format:

git commit -m "feat: Add user login

Implements email/password authentication.

Fixes WOR-123"

Linear will automatically link this commit to issue WOR-123.

Git Hooks for Auto-Updates

Automatically update Linear on every commit:Create post-commit hook:

# Create hook file
touch .git/hooks/post-commit
chmod +x .git/hooks/post-commit

# Edit file
nano .git/hooks/post-commit

Add this content:

#!/bin/bash
COMMIT_MSG=$(git log -1 --pretty=%B)
claude "Update Linear with this commit: $COMMIT_MSG"

Result: Every commit automatically updates the linked Linear issue.

Periodic Sync Schedule

Daily:

End of workday: Sync all active issues
Mark completed tasks as done
Update time estimates

Weekly:

Review milestone progress
Adjust priorities
Update sprint planning

Per Phase:

Close phase milestone
Create phase completion summary
Plan next phase tasks

Notion MCP Setup

Notion is used for major milestone documentation - not daily tracking. Workspace: https://www.notion.so/workally/

Installation
Usage
Templates

Step 1: Create Notion Integration

Access Integrations

Go to https://www.notion.so/my-integrations
Sign in with your WorkAlly Notion account

Create New Integration

Click ”+ New integration”
Name: Claude Code MCP
Associated workspace: Select “WorkAlly”
Type: Internal integration
Click “Submit”

Copy Integration Token

Copy the Internal Integration TokenIt starts with secret_

Get Database ID

Open your Notion project database
Copy URL - looks like:

https://notion.so/workally/1234567890abcdef1234567890abcdef

The database ID is: 1234567890abcdef1234567890abcdef

Share Database with Integration

Open your Notion project database
Click “Share” button (top right)
Click “Invite”
Search for “Claude Code MCP”
Grant Can edit permission
Click “Invite”

Step 2: Configure Claude Code

Add Notion MCP to ~/.claude/config.toml:

[mcp_servers.notion]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-notion"]
env = { NOTION_API_KEY = "secret_YOUR_TOKEN_HERE" }

Replace secret_YOUR_TOKEN_HERE with your integration token.

Step 3: Restart Claude Code

Same as Linear - reload MCP servers.

Step 4: Verify Connection

"Check Notion MCP connection and list my Notion databases"

When to Update Notion

✅ Update Notion for:

Phase completions (Phase 0 done, Phase 1 done, etc.)
MVP launch
Production deployment
Major feature releases
Quarterly reviews

❌ Do NOT update Notion for:

Individual task completions
Daily progress
Bug fixes
Minor updates

Phase Completion Documentation

When you complete a phase:

"Phase 1 (Authentication) is complete. Create a Notion page in the
[Project Name] database documenting:

- Title: 'Phase 1: Authentication Complete - [Date]'
- Summary of implemented features
- Screenshots or demo links
- Deployment URL (staging/production)
- Performance metrics
- Known issues or limitations
- Next steps (Phase 2 preview)"

MVP Launch Documentation

"MVP is ready for launch! Create a comprehensive Notion launch page with:

- Executive summary
- Feature list with screenshots
- Technical architecture diagram
- Deployment details
- Monitoring setup
- User onboarding guide
- Support documentation
- Post-launch roadmap"

Production Deployment Report

"App deployed to production! Document in Notion:

- Deployment timestamp
- Production URL
- Environment variables checklist
- Database migration status
- Monitoring dashboard links
- Incident response plan
- Rollback procedure
- Success metrics baseline"

Phase Completion Template

Ask Claude Code to use this structure:

# Phase [X]: [Phase Name] Complete

**Completion Date:** [Date]
**Duration:** [X weeks/days]
**Status:** ✅ Complete

## Implemented Features
- [Feature 1] - [Brief description]
- [Feature 2] - [Brief description]

## Technical Details
- Framework: Next.js 14
- Database: Supabase PostgreSQL
- Authentication: Supabase Auth
- Deployment: Vercel

## Metrics
- Performance: [Lighthouse scores]
- Test Coverage: [X%]
- Bundle Size: [X KB]

## Screenshots
[Add screenshots or demo video]

## Deployment
- Staging: [URL]
- Production: [URL if deployed]

## Known Issues
- [Issue 1]
- [Issue 2]

## Next Steps
- Phase [X+1] preview
- Priorities for next phase

Milestone Template

# Milestone: [Name]

**Achievement Date:** [Date]
**Impact:** [High/Medium/Low]

## What We Built
[Summary paragraph]

## Key Features
1. [Feature with description]
2. [Feature with description]

## By the Numbers
- Users: [X]
- Performance: [metrics]
- Uptime: [%]

## Challenges Overcome
- [Challenge 1 and solution]

## Learnings
- [Key learning 1]

## Next Milestone
[What's coming next]

Complete Workflow Integration

Step-by-Step: New Project Setup

Create Project Brief

mkdir brief
cd brief
# Create claude.md and plan.md

Initialize Linear Project

"Read brief/plan.md and create a Linear project with all phases and tasks"

Start Development

Begin working on Phase 0 tasks from Linear

Daily Updates

"Update Linear with today's completed tasks"

Complete Phase

"Phase 0 complete! Update Linear milestone and create Notion documentation"

Continue Cycle

Repeat for each phase, updating Linear daily and Notion per major milestone

Recommended Update Schedule

Frequency	Action	Tool
Per Task	Mark task complete	Linear
Daily	Sync progress, update estimates	Linear
Per PR	Link PR to issue	Linear + GitHub
Per Phase	Document completion	Linear + Notion
Per Milestone	Create comprehensive doc	Notion

Troubleshooting

Linear MCP Not Working

Check config:

cat ~/.claude/config.toml | grep -A 3 linear

Verify API key is valid:

curl -H "Authorization: Bearer lin_api_YOUR_KEY" \
     -H "Content-Type: application/json" \
     https://api.linear.app/graphql \
     -d '{"query": "{ viewer { name } }"}'

Reinstall MCP server:

npx @modelcontextprotocol/server-linear --version

Notion MCP Not Connecting

Verify database sharing:

Open Notion database
Check “Claude Code MCP” integration has access
Ensure permission is “Can edit”

Test API token:

curl -H "Authorization: Bearer secret_YOUR_TOKEN" \
     -H "Notion-Version: 2022-06-28" \
     https://api.notion.com/v1/users/me

Updates Not Syncing

Reload MCP servers:

"Reload all MCP servers and verify connections"

Check Claude Code logs:

cat ~/.claude/logs/mcp.log

Restart Claude Code completely:

# Kill all Claude processes
pkill -f claude

# Restart
claude

Best Practices

Linear Best Practices

✅ DO:

Update Linear after each task
Use consistent issue naming
Link all PRs to issues
Use labels and milestones
Add time estimates

❌ DON’T:

Create duplicate issues
Skip linking commits
Forget to close completed issues
Leave issues without assignees

Notion Best Practices

✅ DO:

Document major milestones only
Include screenshots and demos
Add deployment links
Track key metrics
Link to Linear issues

❌ DON’T:

Document every small task
Create pages for bugs
Duplicate Linear info
Skip technical details

Next Step

With MCP configured, start your first project with the discovery phase →

Welcome

Quick Start

What is MCP?

Linear MCP Setup

Step 1: Get Linear API Key

Step 2: Configure Claude Code

Step 3: Restart Claude Code

Step 4: Verify Connection

Creating Projects from plan.md

Daily Progress Updates

Creating New Issues

PR & Commit Linking

Git Hooks for Auto-Updates

Periodic Sync Schedule

Notion MCP Setup

Step 1: Create Notion Integration

Step 2: Configure Claude Code

Step 3: Restart Claude Code

Step 4: Verify Connection

When to Update Notion

Phase Completion Documentation

MVP Launch Documentation

Production Deployment Report

Phase Completion Template

Milestone Template

Complete Workflow Integration

Step-by-Step: New Project Setup

Recommended Update Schedule

Troubleshooting

Best Practices

Linear Best Practices

Notion Best Practices

Next Step

​What is MCP?

​Linear MCP Setup

​Step 1: Get Linear API Key

​Step 2: Configure Claude Code

​Step 3: Restart Claude Code

​Step 4: Verify Connection

​Creating Projects from plan.md

​Daily Progress Updates

​Creating New Issues

​PR & Commit Linking

​Git Hooks for Auto-Updates

​Periodic Sync Schedule

​Notion MCP Setup

​Step 1: Create Notion Integration

​Step 2: Configure Claude Code

​Step 3: Restart Claude Code

​Step 4: Verify Connection

​When to Update Notion

​Phase Completion Documentation

​MVP Launch Documentation

​Production Deployment Report

​Phase Completion Template

​Milestone Template

​Complete Workflow Integration

​Step-by-Step: New Project Setup

​Recommended Update Schedule

​Troubleshooting

​Best Practices

Linear Best Practices

Notion Best Practices

Next Step

What is MCP?

Linear MCP Setup

Step 1: Get Linear API Key

Step 2: Configure Claude Code

Step 3: Restart Claude Code

Step 4: Verify Connection

Creating Projects from plan.md

Daily Progress Updates

Creating New Issues

PR & Commit Linking

Git Hooks for Auto-Updates

Periodic Sync Schedule

Notion MCP Setup

Step 1: Create Notion Integration

Step 2: Configure Claude Code

Step 3: Restart Claude Code

Step 4: Verify Connection

When to Update Notion

Phase Completion Documentation

MVP Launch Documentation

Production Deployment Report

Phase Completion Template

Milestone Template

Complete Workflow Integration

Step-by-Step: New Project Setup

Recommended Update Schedule

Troubleshooting

Best Practices