Skip to content

configuration.md

Latest commit

 

History

History
288 lines (203 loc) · 6.38 KB

configuration.md

File metadata and controls

288 lines (203 loc) · 6.38 KB

Configuration

← Back to Index | ← Installation | Next: Quick Start →

Table of Contents

  1. Getting Your HacknPlan API Key
  2. Claude Code Configuration
  3. Environment Variables
  4. Project-Scoped Configuration
  5. Security Best Practices
  6. Verification

Getting Your HacknPlan API Key

Step 1: Access HacknPlan Settings

  1. Log into HacknPlan
  2. Click your profile icon (top-right)
  3. Select Settings
  4. Navigate to API Beta tab

Step 2: Create API Key

  1. Click Create button
  2. Enter a descriptive name (e.g., "Claude MCP Server")
  3. Copy the generated API key immediately
  4. Important: Store securely - you cannot view it again!

Claude Code Configuration

Method 1: CLI (Recommended)

claude mcp add hacknplan \
  -s user \
  -e HACKNPLAN_API_KEY=your-api-key \
  -e HACKNPLAN_DELETION_CACHE_SIZE=1000 \
  -- node /path/to/hacknplan-mcp/dist/index.js

Method 2: Manual Configuration

Edit ~/.claude.json:

{
  "mcpServers": {
    "hacknplan": {
      "command": "node",
      "args": ["/path/to/hacknplan-mcp/dist/index.js"],
      "env": {
        "HACKNPLAN_API_KEY": "your-api-key-here",
        "HACKNPLAN_DEFAULT_PROJECT": "230954",
        "HACKNPLAN_DELETION_CACHE_SIZE": "1000"
      }
    }
  }
}

Path Notes:

  • Windows: C:\path\to\hacknplan-mcp\dist\index.js
  • macOS/Linux: /absolute/path/to/hacknplan-mcp/dist/index.js
  • Use absolute paths, not relative

Environment Variables

Required Variables

HACKNPLAN_API_KEY

Required: Yes Type: String Description: Your HacknPlan API authentication key

export HACKNPLAN_API_KEY="sk_hacknplan_abc123..."

Security: Must be set as environment variable. CLI arguments (e.g., --api-key=...) are rejected to prevent exposure in process listings.

Optional Variables

HACKNPLAN_DEFAULT_PROJECT

Required: No Type: Number (project ID) Description: Default project ID when not specified in tool calls

export HACKNPLAN_DEFAULT_PROJECT="230954"

When to use: Working primarily with one project to avoid passing projectId repeatedly.

HACKNPLAN_SLIM_MODE

Required: No Type: Boolean (true or false) Default: false Description: Enable slim mode (26 core tools vs 89 full tools)

export HACKNPLAN_SLIM_MODE="true"

Impact: ~71% reduction in tool loading context. See Slim Mode Guide.

HACKNPLAN_OUTPUT_VERBOSITY

Required: No Type: slim | full Default: full Description: Response detail level

export HACKNPLAN_OUTPUT_VERBOSITY="slim"
  • slim: Minimal fields + index arrays for quick lookups
  • full: Complete objects with all fields

HACKNPLAN_DELETION_CACHE_SIZE

Required: No Type: Number Default: 1000 Description: LRU cache capacity for deleted item recovery

export HACKNPLAN_DELETION_CACHE_SIZE="2000"

See Deletion Safety Guide.

HACKNPLAN_REQUIRE_DELETE_CONFIRMATION

Required: No Type: Boolean (true or false) Default: false Description: Enforce 2-step confirmation for ALL deletions

export HACKNPLAN_REQUIRE_DELETE_CONFIRMATION="true"

Modes:

  • false (default): Single-step deletion with auto-recovery
  • true: All deletions require explicit confirmation via confirm_deletion

Project-Scoped Configuration

Override defaults for specific directories using .mcp.json:

Creating .mcp.json

{
  "HACKNPLAN_DEFAULT_PROJECT": 230809
}

Place in your working directory to set project-specific defaults.

Resolution Order

When determining which project to use:

  1. Explicit parameter: projectId in tool call
  2. Local config: .mcp.json in current working directory
  3. Environment variable: HACKNPLAN_DEFAULT_PROJECT
  4. Error: Display available projects list

Use Cases

  • Multi-project workflows: Different projects per directory
  • Team collaboration: Share .mcp.json in repositories
  • Context switching: Automatic project selection based on location

Security Best Practices

API Key Storage

✅ Do:

  • Store in environment variables
  • Use secret management tools (Vault, AWS Secrets Manager)
  • Set restrictive file permissions on config files (chmod 600 ~/.claude.json)

❌ Don't:

  • Commit API keys to version control
  • Pass as CLI arguments
  • Share API keys in screenshots or logs
  • Store in plaintext files

Environment Variable Security

# Linux/macOS - Add to ~/.bashrc or ~/.zshrc
export HACKNPLAN_API_KEY="your-key"

# Windows - Use User Environment Variables (not System)
# Settings > System > About > Advanced system settings > Environment Variables

Rotating Keys

  1. Create new API key in HacknPlan
  2. Update environment variable
  3. Restart MCP server
  4. Verify with claude mcp list
  5. Delete old key in HacknPlan

Verification

Check MCP Server Status

# List configured servers
claude mcp list

# Should show:
# hacknplan: node /path/to/dist/index.js - Connected

Test Connection

# From Claude Code
# Call any simple tool like list_projects to verify

Troubleshooting Connection Issues

Server not listed:

# Verify configuration file exists
cat ~/.claude.json

# Check for JSON syntax errors

Connection failed:

# Verify API key is set
echo $HACKNPLAN_API_KEY

# Rebuild server
cd /path/to/hacknplan-mcp
npm run build

Permission denied:

# Check file permissions
ls -la ~/.claude.json
chmod 600 ~/.claude.json

Next Steps

With configuration complete:

  1. Quick Start Guide → - Make your first API calls
  2. Slim Mode Guide - Optimize context usage
  3. Deletion Safety Guide - Configure deletion protection

See Also: