> ## Documentation Index
> Fetch the complete documentation index at: https://docs.weventures.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Setup (Linear & Notion)

> Configure Linear and Notion MCP servers for automated project tracking

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

## 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

<img src="https://mintcdn.com/weventuresai/UITuWVvu87xnO8BJ/images/linear-logo.png?fit=max&auto=format&n=UITuWVvu87xnO8BJ&q=85&s=80743f29d822c42b5a54417b4e701fd5" alt="Linear" className="rounded-lg my-4" style={{ maxWidth: '200px' }} width="2000" height="2000" data-path="images/linear-logo.png" />

Linear is our primary project tracking tool for day-to-day task management.

**Workspace:** [https://linear.app/workally/projects/all](https://linear.app/workally/projects/all)

<Tabs>
  <Tab title="Installation">
    ### Step 1: Get Linear API Key

    <Steps>
      <Step title="Access Linear Settings">
        1. Go to [https://linear.app/workally/settings/api](https://linear.app/workally/settings/api)
        2. Sign in with your WorkAlly account
      </Step>

      <Step title="Create API Key">
        1. Click **"Create new personal API key"**
        2. Name: `Claude Code MCP`
        3. Description: `For automated task tracking via Claude Code`
        4. Click **"Create key"**
      </Step>

      <Step title="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>
    </Steps>

    ### Step 2: Configure Claude Code

    Add Linear MCP to your Claude Code configuration file.

    **Config location:** `~/.claude/config.toml`

    ```toml theme={null}
    [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

    <CodeGroup>
      ```bash CLI theme={null}
      # Reload MCP servers
      claude --reload-mcp
      ```

      ```bash VS Code Extension theme={null}
      # Reload VS Code window
      # Press: Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows)
      # Type: "Reload Window"
      # Press Enter
      ```
    </CodeGroup>

    ### 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.
  </Tab>

  <Tab title="Usage">
    ### 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:**

    ```bash theme={null}
    git commit -m "feat: Add user login

    Implements email/password authentication.

    Fixes WOR-123"
    ```

    Linear will automatically link this commit to issue WOR-123.
  </Tab>

  <Tab title="Automation">
    ### Git Hooks for Auto-Updates

    Automatically update Linear on every commit:

    **Create post-commit hook:**

    ```bash theme={null}
    # Create hook file
    touch .git/hooks/post-commit
    chmod +x .git/hooks/post-commit

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

    **Add this content:**

    ```bash theme={null}
    #!/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
  </Tab>
</Tabs>

***

## Notion MCP Setup

<img src="https://mintcdn.com/weventuresai/UITuWVvu87xnO8BJ/images/Notion-logo.svg.png?fit=max&auto=format&n=UITuWVvu87xnO8BJ&q=85&s=c9a8ce20b03a38a009b9ff67fdee2b68" alt="Notion" className="rounded-lg my-4" style={{ maxWidth: '200px' }} width="1024" height="1024" data-path="images/Notion-logo.svg.png" />

Notion is used for **major milestone documentation** - not daily tracking.

**Workspace:** [https://www.notion.so/workally/](https://www.notion.so/workally/)

<Tabs>
  <Tab title="Installation">
    ### Step 1: Create Notion Integration

    <Steps>
      <Step title="Access Integrations">
        1. Go to [https://www.notion.so/my-integrations](https://www.notion.so/my-integrations)
        2. Sign in with your WorkAlly Notion account
      </Step>

      <Step title="Create New Integration">
        1. Click **"+ New integration"**
        2. **Name:** `Claude Code MCP`
        3. **Associated workspace:** Select "WorkAlly"
        4. **Type:** Internal integration
        5. Click **"Submit"**
      </Step>

      <Step title="Copy Integration Token">
        Copy the **Internal Integration Token**

        It starts with `secret_`
      </Step>

      <Step title="Get Database ID">
        1. Open your Notion project database
        2. Copy URL - looks like:

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

        3. The database ID is: `1234567890abcdef1234567890abcdef`
      </Step>

      <Step title="Share Database with Integration">
        1. Open your Notion project database
        2. Click **"Share"** button (top right)
        3. Click **"Invite"**
        4. Search for **"Claude Code MCP"**
        5. Grant **Can edit** permission
        6. Click **"Invite"**
      </Step>
    </Steps>

    ### Step 2: Configure Claude Code

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

    ```toml theme={null}
    [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"
    ```
  </Tab>

  <Tab title="Usage">
    ### 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"
    ```
  </Tab>

  <Tab title="Templates">
    ### Phase Completion Template

    Ask Claude Code to use this structure:

    ```markdown theme={null}
    # 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

    ```markdown theme={null}
    # 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]
    ```
  </Tab>
</Tabs>

***

## Complete Workflow Integration

### Step-by-Step: New Project Setup

<Steps>
  <Step title="Create Project Brief">
    ```bash theme={null}
    mkdir brief
    cd brief
    # Create claude.md and plan.md
    ```
  </Step>

  <Step title="Initialize Linear Project">
    ```
    "Read brief/plan.md and create a Linear project with all phases and tasks"
    ```
  </Step>

  <Step title="Start Development">
    Begin working on Phase 0 tasks from Linear
  </Step>

  <Step title="Daily Updates">
    ```
    "Update Linear with today's completed tasks"
    ```
  </Step>

  <Step title="Complete Phase">
    ```
    "Phase 0 complete! Update Linear milestone and create Notion documentation"
    ```
  </Step>

  <Step title="Continue Cycle">
    Repeat for each phase, updating Linear daily and Notion per major milestone
  </Step>
</Steps>

### 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

<AccordionGroup>
  <Accordion title="Linear MCP Not Working">
    **Check config:**

    ```bash theme={null}
    cat ~/.claude/config.toml | grep -A 3 linear
    ```

    **Verify API key is valid:**

    ```bash theme={null}
    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:**

    ```bash theme={null}
    npx @modelcontextprotocol/server-linear --version
    ```
  </Accordion>

  <Accordion title="Notion MCP Not Connecting">
    **Verify database sharing:**

    1. Open Notion database
    2. Check "Claude Code MCP" integration has access
    3. Ensure permission is "Can edit"

    **Test API token:**

    ```bash theme={null}
    curl -H "Authorization: Bearer secret_YOUR_TOKEN" \
         -H "Notion-Version: 2022-06-28" \
         https://api.notion.com/v1/users/me
    ```
  </Accordion>

  <Accordion title="Updates Not Syncing">
    **Reload MCP servers:**

    ```
    "Reload all MCP servers and verify connections"
    ```

    **Check Claude Code logs:**

    ```bash theme={null}
    cat ~/.claude/logs/mcp.log
    ```

    **Restart Claude Code completely:**

    ```bash theme={null}
    # Kill all Claude processes
    pkill -f claude

    # Restart
    claude
    ```
  </Accordion>
</AccordionGroup>

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Linear Best Practices" icon="list-check">
    ✅ **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
  </Card>

  <Card title="Notion Best Practices" icon="book">
    ✅ **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
  </Card>
</CardGroup>

***

<Card title="Next Step" icon="arrow-right" href="/ai-development/prompting/discovery">
  With MCP configured, start your first project with the discovery phase →
</Card>