Canary MCP Server Setup

This skill walks users through setting up the Magnet MCP server to use the canary environment (https://canary.magnet.run) with their MCP client (Claude Code, Cursor, Claude Desktop).

Important: This setup configures the MCP server to talk to the Magnet canary environment, not production or localhost.

When to Use This Skill

Use this skill when the user requests:

Setting up the MCP server for the canary environment
Testing against the canary Magnet instance
Configuring their MCP client to use canary
Troubleshooting canary MCP connection issues

Instructions

Step 1: Check Prerequisites

Verify the development environment is ready:

# Check Node.js version (must be >= 22.2.0)
node --version

# Check pnpm is installed
pnpm --version

# Check if dependencies are installed
ls node_modules/.bin/tsc 2>/dev/null && echo "Dependencies installed" || echo "Need to install dependencies"

If dependencies are missing, install them:

pnpm install

Step 2: Confirm Project-Specific Scope

Important: This setup configures the MCP server for the magnet-app project directory only. The MCP server will NOT be available when working in other directories.

Use AskUserQuestion to confirm the user understands:

Question: "This will configure the MCP server for your magnet-app project directory only. It will NOT be available globally in other projects. Do you understand and want to proceed?" Options:

"Yes, I understand it's project-specific" - Continue with setup
"No, I need global setup" - Inform user that global setup requires manual configuration in ~/.claude/ and is not covered by this skill

If the user needs global setup, explain:

Global MCP configuration is not officially supported by Claude Code
They would need to manually configure ~/.claude/settings.json or use the plugins system
Recommend using project-specific setup for most use cases

Step 3: Build the MCP Server Project

Build the TypeScript project:

pnpm build

Verify the build succeeded:

ls -la dist/index.js

Step 4: Check for Existing Environment Configuration

Check if .env file exists with API key:

if [ -f .env ]; then
  echo ".env file exists"
  grep -q "MAGNET_API_KEY" .env && echo "API key configured" || echo "API key missing"
else
  echo "No .env file found"
fi

Step 5: Gather API Key

Use AskUserQuestion to get the Magnet API key if not already configured. The API key must come from the canary Magnet instance.

Question: "Do you have an API key from the Magnet canary environment?" Options:

"Yes, I have one" - Prompt them to provide it
"No, I need to get one" - Direct them to https://canary.magnet.run/settings to generate one

If they provide a key, you can optionally store it for reference:

echo "MAGNET_API_KEY=<their-key>" > .env
echo "MAGNET_WEB_API_BASE_URL=https://canary.magnet.run" >> .env

Step 6: Detect MCP Client

Use AskUserQuestion to determine which MCP client they're using:

Question: "Which MCP client are you using?" Options:

"Claude Code" - Will configure .mcp.json file
"Cursor" - Will configure ~/.cursor/mcp.json
"Claude Desktop" - Will configure ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

Step 7: Find User's magnet-app Directory

Important: The default setup location should be the user's magnet-app repo, since that's where they'll be doing development work and need the MCP tools available.

# Common locations to check for magnet-app
ls -d ~/magnet-app 2>/dev/null || \
ls -d ~/Projects/magnet-app 2>/dev/null || \
ls -d ~/Code/magnet-app 2>/dev/null || \
echo "magnet-app not found in common locations"

If not found, ask: Question: "Where is your magnet-app repository located?"

Step 8: Check Existing MCP Configuration

Claude Code uses .mcp.json files, NOT settings.json for MCP servers. The settings.json schema does not support the mcpServers field.

# Check for existing .mcp.json in magnet-app
cat ~/magnet-app/.mcp.json 2>/dev/null || echo "No .mcp.json found"

Cursor:

cat ~/.cursor/mcp.json 2>/dev/null

Claude Desktop (macOS):

cat ~/Library/Application\ Support/Claude/claude_desktop_config.json 2>/dev/null

Step 9: Generate Configuration

Get the absolute path to the MCP server:

pwd  # Should be /path/to/magnet-mcp-server

Create the .mcp.json file structure. Important: This always points to the canary Magnet API at https://canary.magnet.run.

{
  "mcpServers": {
    "magnet-canary": {
      "command": "node",
      "args": ["/absolute/path/to/magnet-mcp-server/dist/index.js"],
      "env": {
        "MAGNET_API_KEY": "<api-key-here>",
        "MAGNET_WEB_API_BASE_URL": "https://canary.magnet.run"
      }
    }
  }
}

For development (rebuilds before running):

{
  "mcpServers": {
    "magnet-canary": {
      "command": "pnpm",
      "args": ["--dir", "/absolute/path/to/magnet-mcp-server", "dev"],
      "env": {
        "MAGNET_API_KEY": "<api-key-here>",
        "MAGNET_WEB_API_BASE_URL": "https://canary.magnet.run"
      }
    }
  }
}

Step 10: Create .mcp.json in magnet-app

Create the .mcp.json file in the user's magnet-app directory (the default location).

Ask user: Question: "How should the canary server be named?" Options:

"magnet-canary (recommended)" - Keeps production and local configs separate
"magnet (replace existing)" - Replaces any existing magnet configuration

Important: The .mcp.json file is project-specific. It only makes the MCP server available when working in that directory.

Step 11: Add .mcp.json to .gitignore

Critical: The .mcp.json file contains the API key and must NOT be committed to git.

Check and update .gitignore in the magnet-app directory:

grep -E "^\.mcp\.json$" ~/magnet-app/.gitignore 2>/dev/null || echo ".mcp.json" >> ~/magnet-app/.gitignore

Step 12: Verify Setup

After updating the configuration, provide next steps:

Restart the MCP client to load the new configuration
Verify the server loads by checking available tools
Test a simple command like listing issues

For Claude Code:

Run /mcp to verify the magnet-canary server is connected and shows its tools

Step 13: Troubleshooting

If the server doesn't connect, check:

API Key: Ensure MAGNET_API_KEY is valid and from the canary Magnet instance
Path: Verify the absolute path to dist/index.js is correct
Build: Make sure pnpm build completed successfully
Node version: Confirm Node.js >= 22.2.0
Network: Ensure you can reach https://canary.magnet.run

Common errors:

"MAGNET_API_KEY is not set" - API key missing or not being passed
"Cannot find module" - Build not complete or wrong path
401/403 errors - API key is invalid or from wrong environment (production vs canary)
Network errors - Check connectivity to canary.magnet.run

Examples

Example 1: First-Time Canary Setup

User: "I want to test the MCP server against canary"

Actions:

Check Node.js version and pnpm
Run pnpm install if needed
Run pnpm build
Ask for API key from canary Magnet instance
Detect they're using Claude Code
Find their magnet-app directory
Create .mcp.json in magnet-app with magnet-canary config
Add .mcp.json to magnet-app's .gitignore
Instruct to restart Claude Code in magnet-app directory

Example 2: Adding Canary Alongside Production

User: "I need to also connect to canary for testing"

Actions:

Verify build is current (pnpm build)
Check existing .mcp.json in magnet-app
Add magnet-canary config alongside existing magnet config
Ask them to get an API key from canary if they don't have one
Explain they can use both production and canary by using different server names

Example 3: Troubleshooting Canary Connection

User: "The canary MCP server isn't working"

Actions:

Check if dist/index.js exists
Verify Node.js version
Test running server directly: MAGNET_WEB_API_BASE_URL=https://canary.magnet.run MAGNET_API_KEY=xxx node dist/index.js
Check API key is from canary Magnet instance (not production or local)
Verify .mcp.json has MAGNET_WEB_API_BASE_URL set to https://canary.magnet.run
Verify .mcp.json has correct absolute path to dist/index.js
Confirm user restarted Claude Code after config changes

Notes

NOT A GLOBAL SETUP - This configures the MCP server for the magnet-app project directory only. It will NOT be available in other projects.
This skill configures for canary environment - it always points to https://canary.magnet.run
API key must be from canary instance - production or local API keys won't work
Claude Code uses .mcp.json files - NOT settings.json for MCP servers
.mcp.json is project-specific - it only works when Claude Code is running in that directory
Always use absolute paths in MCP configuration
The "magnet-canary" name helps distinguish from production and local
Restart Claude Code after configuration changes
Use pnpm dev for development builds (rebuilds before running)
Always add .mcp.json to .gitignore - it contains the API key

canary-setup

Canary MCP Server Setup

When to Use This Skill

Instructions

Step 1: Check Prerequisites

Step 2: Confirm Project-Specific Scope

Step 3: Build the MCP Server Project

Step 4: Check for Existing Environment Configuration

Step 5: Gather API Key

Step 6: Detect MCP Client

Step 7: Find User's magnet-app Directory

Step 8: Check Existing MCP Configuration

Step 9: Generate Configuration

Step 10: Create .mcp.json in magnet-app

Step 11: Add .mcp.json to .gitignore

Step 12: Verify Setup

Step 13: Troubleshooting

Examples

Example 1: First-Time Canary Setup

Example 2: Adding Canary Alongside Production

Example 3: Troubleshooting Canary Connection

Notes