MCP Setup Guide

Before ULPI Skills MCP Setup
After ULPI Skills MCP Setup

Your AI coding assistant can’t access your team’s workflows:

❌ AI doesn’t know your deployment procedure
❌ AI can’t follow your coding standards
❌ 30 minutes wasted explaining the same process to AI every time
❌ AI generates inconsistent code across team members
❌ Manual copy-paste of workflows from wikis
❌ Risk of AI using outdated or wrong procedures
❌ No access to company-specific patterns

Customer Success Story:“Before MCP setup, we spent 30 minutes per day explaining our deployment process to AI. After 10-minute MCP setup, our AI knows every workflow. We say ‘deploy to staging’ and it executes our exact 8-step procedure—no questions, no mistakes. Setup time: 10 minutes. Time saved per week: 2.5 hours.” — Senior Engineer, E-commerce Platform with 500K Orders/Day

What is MCP?

MCP (Model Context Protocol) is an open standard created by Anthropic that enables AI assistants to interact with external tools and data sources.

How It Works

AI Assistant (Claude, GPT-4, Gemini, etc.)
    ↓
MCP Client (built into your IDE/tool)
    ↓
MCP Server (@ulpi/mcp-server-skills)
    ↓
ULPI API (api.ulpi.io)
    ↓
Your Skills Database

The ULPI Skills MCP Server

NPM Package

@ulpi/mcp-server-skillsRuns locally on your machine

Secure Authentication

Uses your ULPI API keyKeys never leave your machine

Real-Time Updates

Skills update automatically when you modify them1-hour cache TTL (configurable)

Universal Compatibility

Works with 40+ MCP-compatible AI toolsClaude, Cursor, Windsurf, Continue, Cline, Zed, and more

Benefits:

Real-time updates: Skills update automatically when you modify them
Secure: API keys never leave your machine, stored in local config files
Fast: Local caching reduces API calls (1-hour TTL)
Universal: Works with any MCP-compatible AI assistant

Time to Setup: 10 minutes (includes installation, configuration, and verification)

Prerequisites

Before installing the MCP server, ensure you have:

Node.js 18 or Later

The MCP server requires Node.js 18+ to run.Check your version:

node --version
# Should show v18.0.0 or higher

Install Node.js:

macOS/Linux: Use nvm (recommended) or download from nodejs.org
Windows: Download installer from nodejs.org

Recommended: Install latest LTS version (currently v22.x)

ULPI Account with Skills Product

You need an active ULPI Skills subscription.Sign up: app.ulpi.ioPlans: Starter (

19/mo), Pro (

69/mo), or Enterprise ($199/mo)Free Trial: 14 days, no credit card required

Connected Repository

Connect at least one repository to ULPI to enable tech stack detection.How to connect:

Go to app.ulpi.io/repositories
Click “Connect Repository”
Authorize GitHub/GitLab/Bitbucket/Gitea
Select repositories to connect

Tech stack detection runs automatically on first connection (takes 1-30 seconds depending on repo size).

API Key with Skills Scope

Generate an API key with repo:{id}:skills scope.How to generate:

Go to app.ulpi.io/api-keys
Click “Create API Key”
Name: “Skills MCP Server”
Environment: live (production)
Scopes: Select repo:{your_repo_id}:skills
Click “Create”
Copy the token (shown only once)

Format: ulpi_live_...

Store your API key securely. Never commit it to version control or share it publicly.

Installation Methods

Choose the installation method that works best for your workflow:

Method 1: npx (Recommended)
Method 2: Global Install
Method 3: Project-Local Install
Method 4: Docker

Best for: Most users—no global installation requiredHow it works: npx downloads and runs the latest version automaticallyConfiguration:

{
  "mcpServers": {
    "ulpi-skills": {
      "command": "npx",
      "args": ["-y", "@ulpi/mcp-server-skills"],
      "env": {
        "ULPI_API_KEY": "ulpi_live_...",
        "ULPI_REPOSITORY_ID": "123"
      }
    }
  }
}

Pros:

✅ Always uses latest version (auto-updates)
✅ No manual installation needed
✅ Works out of the box

Cons:

❌ Slightly slower first-time startup (~2 seconds)
❌ Requires internet connection

IDE-Specific Configuration

Configure MCP server for your AI coding tool:

Claude Desktop
Cursor
Windsurf
VSCode (via Continue)
VSCode (via Cline)
Zed
Claude Code (CLI)

Config file location:

macOS
Windows
Linux

~/Library/Application Support/Claude/claude_desktop_config.json

Create if doesn’t exist:

mkdir -p ~/Library/Application\ Support/Claude
touch ~/Library/Application\ Support/Claude/claude_desktop_config.json

Add configuration:

{
  "mcpServers": {
    "ulpi-skills": {
      "command": "npx",
      "args": ["-y", "@ulpi/mcp-server-skills"],
      "env": {
        "ULPI_API_KEY": "ulpi_live_YOUR_KEY_HERE",
        "ULPI_REPOSITORY_ID": "123"
      }
    }
  }
}

Restart Claude Desktop for changes to take effect.Verify:

Look for 🔌 icon in Claude Desktop
Click icon to see “ulpi-skills” server
Check for available tools (get_skill, list_skills, etc.)

More AI Tools: ULPI Skills MCP server works with 40+ MCP-compatible tools including Trae, Kiro, Perplexity Desktop, BoltAI, Augment Code, Qodo Gen, and more. See full list in MCP Integration docs.

Environment Variables

Configure the MCP server behavior with environment variables:

Required Variables

ULPI_API_KEY (required)

Your ULPI API key with repo:{id}:skills scope
Format: ulpi_live_... or ulpi_test_...
How to get: app.ulpi.io/api-keys

ULPI_REPOSITORY_ID (required)

The ID of the repository to fetch skills for
Format: Numeric string (e.g., "123")
How to get: Check repository details at app.ulpi.io/repositories

Optional Variables

ULPI_API_URL

ULPI API base URL (default: https://api.ulpi.io)
Override for self-hosted or staging environments
Example: https://staging-api.ulpi.io

ULPI_CACHE_TTL

Cache time-to-live in seconds (default: 3600 = 1 hour)
Example: 7200 (2 hours)
Min: 300 (5 minutes)
Max: 86400 (24 hours)

ULPI_CACHE_ENABLED

Enable or disable local skill caching (default: true)
Values: true, false
When to disable: Testing skill updates in real-time

ULPI_LOG_LEVEL

Logging verbosity level (default: info)
Levels: error, warn, info, debug, trace
Development: Use debug or trace
Production: Use info or warn

ULPI_TIMEOUT

API request timeout in milliseconds (default: 30000 = 30 seconds)
Example: 60000 (1 minute)
Min: 5000 (5 seconds)
Max: 300000 (5 minutes)

Complete Configuration Example

{
  "mcpServers": {
    "ulpi-skills": {
      "command": "npx",
      "args": ["-y", "@ulpi/mcp-server-skills"],
      "env": {
        "ULPI_API_KEY": "ulpi_live_...",
        "ULPI_REPOSITORY_ID": "123",
        "ULPI_API_URL": "https://api.ulpi.io",
        "ULPI_CACHE_TTL": "3600",
        "ULPI_CACHE_ENABLED": "true",
        "ULPI_LOG_LEVEL": "info",
        "ULPI_TIMEOUT": "30000"
      }
    }
  }
}

Verification

Confirm the MCP server is working correctly:

Check Server Connection

In your AI assistant:

Look for MCP server indicator (usually a 🔌 or connection icon)
Verify “ulpi-skills” appears in the list of connected servers
Check for “Connected” or green status indicator

Troubleshooting:

No server showing? Restart your IDE/app
Red status? Check API key and repository ID
Yellow status? Network or API issues

List Available Skills

Ask your AI assistant:

“List all available ULPI skills”

Expected response: The AI should call the list_skills MCP tool and return a list of skills filtered for your repository’s tech stack.Example output:

Available skills for your repository:
Create Laravel API Endpoint
Laravel Database Migration
Write PHPUnit Tests
Git Commit Best Practices
Database Query Optimization
Implement Laravel Queue Job

Fetch a Specific Skill

Ask your AI assistant:

“Show me the ‘Create Laravel API Endpoint’ skill”

Expected behavior: The AI should call get_skill with the skill name and return the full skill content (prerequisites, steps, testing, etc.).Verify:

Skill content is displayed
Prerequisites section is present
Steps are formatted correctly
Testing section is included

Use a Skill

Ask your AI assistant:

“Use the ‘Create Laravel API Endpoint’ skill to create a /api/users endpoint”

Expected behavior: The AI should:

Fetch the skill via MCP
Follow the skill’s steps
Generate code based on the skill workflow
Ask clarifying questions if needed

Verify:

AI follows skill structure
Generated code matches skill patterns
AI references skill prerequisites

Advanced Configuration

Multi-Repository Setup

Use different skills per project:

{
  "mcpServers": {
    "ulpi-skills-frontend": {
      "command": "npx",
      "args": ["-y", "@ulpi/mcp-server-skills"],
      "env": {
        "ULPI_API_KEY": "ulpi_live_...",
        "ULPI_REPOSITORY_ID": "123"
      }
    },
    "ulpi-skills-backend": {
      "command": "npx",
      "args": ["-y", "@ulpi/mcp-server-skills"],
      "env": {
        "ULPI_API_KEY": "ulpi_live_...",
        "ULPI_REPOSITORY_ID": "456"
      }
    }
  }
}

Usage:

AI assistant sees both servers
Skills filtered by each repository’s tech stack
Useful for polyglot codebases (Laravel + React)

Environment-Specific API Keys

Use different keys for different environments:

{
  "mcpServers": {
    "ulpi-skills-prod": {
      "command": "npx",
      "args": ["-y", "@ulpi/mcp-server-skills"],
      "env": {
        "ULPI_API_KEY": "ulpi_live_...",
        "ULPI_REPOSITORY_ID": "123"
      }
    },
    "ulpi-skills-test": {
      "command": "npx",
      "args": ["-y", "@ulpi/mcp-server-skills"],
      "env": {
        "ULPI_API_KEY": "ulpi_test_...",
        "ULPI_REPOSITORY_ID": "456"
      }
    }
  }
}

When to use:

Testing new skills before production
Separate skill sets for staging/prod
Development team vs. production team access

Troubleshooting

Error: 'npx' is not recognized

Problem: Windows reports 'npx' is not recognized as an internal or external commandCause: Node.js not installed or not in PATHSolution:

Install Node.js from nodejs.org
Restart your terminal/IDE
Verify: node --version and npx --version

Alternative: Use full path to npx:

{
  "command": "C:\\Program Files\\nodejs\\npx.cmd",
  "args": ["-y", "@ulpi/mcp-server-skills"]
}

Error: 401 Unauthorized

Problem: MCP server returns 401 authentication errorCause: Invalid or expired API keySolution:

Verify API key format: ulpi_live_... or ulpi_test_...
Check key hasn’t expired (check app.ulpi.io/api-keys)
Verify key has repo:{id}:skills scope
Regenerate key if needed

Error: 403 Forbidden

Problem: MCP server returns 403 forbidden errorCause: API key doesn’t have correct scopeSolution:

Check API key scopes at app.ulpi.io/api-keys
Verify scope includes repo:{repository_id}:skills
Create new key with correct scope if needed

Example correct scope:

repo:123:skills

Incorrect scopes:

repo:456:skills     // Wrong repository ID
repo:123:docs       // Wrong feature (docs vs skills)
tenant:all          // Too broad, need specific repo scope

Error: 404 Repository Not Found

Problem: API returns 404 for repositoryCause: Repository ID doesn’t exist or not connectedSolution:

Verify repository ID at app.ulpi.io/repositories
Check repository is connected (not just added)
Use correct numeric ID (not repository name)

Find your repository ID:

Go to repository details page
Look for “Repository ID: 123” in header
Use this number in ULPI_REPOSITORY_ID

Skills List is Empty

Problem: list_skills returns no skillsCause: Tech stack not detected or no matching skillsSolution:

Check tech stack detection:
- Go to repository settings
- View “Detected Technologies”
- If empty, trigger detection by pushing a commit
Verify public skills match your tech stack:
- Public skills filter by tech stack
- If using uncommon tech stack, create custom skills
Check custom skills:
- Verify custom skills are marked “Active”
- Check tech stack filters on custom skills

Force refresh cache:

"env": {
  "ULPI_CACHE_ENABLED": "false"
}

MCP Server Not Connecting

Problem: IDE/app doesn’t show MCP server connectionCause: Configuration file syntax error or wrong locationSolution:

Validate JSON syntax:
- Use jsonlint.com to check for syntax errors
- Common errors: missing commas, trailing commas, unquoted strings
Verify config file location:
- Check platform-specific paths (see IDE sections above)
- Ensure file exists: ls ~/.config/Claude/claude_desktop_config.json
Restart IDE/app completely:
- Quit application (don’t just close window)
- Restart
- Wait 10 seconds for MCP server to initialize
Check logs:
- Claude Desktop logs: ~/Library/Logs/Claude/
- Cursor logs: View → Output → Select “MCP” from dropdown
- VSCode logs: View → Output → Select “Continue” or “Cline”

Slow Performance / Timeouts

Problem: MCP server slow or times outCause: Network issues, API rate limiting, or slow cacheSolution:

Increase timeout:

"env": {
  "ULPI_TIMEOUT": "60000"  // 1 minute
}

Check internet connection:
- Test API directly: curl https://api.ulpi.io/health
- Verify no firewall blocking API requests

Enable caching:

"env": {
  "ULPI_CACHE_ENABLED": "true",
  "ULPI_CACHE_TTL": "7200"  // 2 hours
}

Check API rate limits:
- View usage at app.ulpi.io/usage
- Upgrade plan if hitting rate limits

Cache Not Updating

Problem: Skill changes not appearing in AI assistantCause: Cache TTL hasn’t expiredSolution:

Clear cache manually:
- Delete cache directory (usually ~/.ulpi/cache/)
- Restart MCP server

Reduce cache TTL:

"env": {
  "ULPI_CACHE_TTL": "300"  // 5 minutes
}

Disable cache during development:

"env": {
  "ULPI_CACHE_ENABLED": "false"
}

Force refresh:
- Restart IDE/app
- MCP server reinitializes and fetches latest skills

Updating the MCP Server

Keep your MCP server up-to-date for latest features and bug fixes:

npx (Auto-Update)
Global Install
Project-Local

No action needed!If using npx, the latest version is automatically downloaded on each run.Force clear npx cache:

npx clear-npx-cache
npx -y @ulpi/mcp-server-skills --version

After updating:

Restart your IDE/app
Verify version: Check logs or ask AI assistant
Test skill fetching

Security Best Practices

Protect your API key! Never commit API keys to version control or share them publicly.

Use .gitignore

Add config files to .gitignore:

# ULPI MCP Config
claude_desktop_config.json
mcp_config.json
.continue/config.json
.cline/mcp_settings.json

Rotate API Keys Regularly

Recommended rotation schedule:

Development keys: Every 90 days
Production keys: Every 30 days
Compromised keys: Immediately

Rotation process:

Generate new API key at app.ulpi.io/api-keys
Update config files with new key
Restart MCP servers
Verify working
Revoke old API key

Next Steps

Use Your First Skill

Start using skills in your AI coding workflow

Create Custom Skills

Build team-specific skills for your unique workflows

How Skills Work

Understand the technical architecture behind skills

Need help? Check our FAQ or contact support at support@ulpi.io

Getting Started

Documentation

Skills

Coordination

Memory

Hooks

Tasks

Help & Security

What is MCP?

How It Works

The ULPI Skills MCP Server

NPM Package

Secure Authentication

Real-Time Updates

Universal Compatibility

Prerequisites

Installation Methods

IDE-Specific Configuration

Environment Variables

Required Variables

Optional Variables

Complete Configuration Example

Verification

Advanced Configuration

Multi-Repository Setup

Environment-Specific API Keys

Troubleshooting

Updating the MCP Server

Security Best Practices

Use .gitignore

Rotate API Keys Regularly

Next Steps

Use Your First Skill

Create Custom Skills

How Skills Work

Getting Started

Documentation

Skills

Coordination

Memory

Hooks

Tasks

Help & Security

​What is MCP?

​How It Works

​The ULPI Skills MCP Server

NPM Package

Secure Authentication

Real-Time Updates

Universal Compatibility

​Prerequisites

​Installation Methods

​IDE-Specific Configuration

​Environment Variables

​Required Variables

​Optional Variables

​Complete Configuration Example

​Verification

​Advanced Configuration

​Multi-Repository Setup

​Environment-Specific API Keys

​Troubleshooting

​Updating the MCP Server

​Security Best Practices

​Use .gitignore

​Rotate API Keys Regularly

​Next Steps

Use Your First Skill

Create Custom Skills

How Skills Work

What is MCP?

How It Works

The ULPI Skills MCP Server

Prerequisites

Installation Methods

IDE-Specific Configuration

Environment Variables

Required Variables

Optional Variables

Complete Configuration Example

Verification

Advanced Configuration

Multi-Repository Setup

Environment-Specific API Keys

Troubleshooting

Updating the MCP Server

Security Best Practices

Use .gitignore

Rotate API Keys Regularly

Next Steps