> ## Documentation Index
> Fetch the complete documentation index at: https://ulpi.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP Setup Guide
> Detailed guide for installing and configuring the ULPI Skills MCP server
**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
**Your AI has instant access to all your workflows:**
* ✅ AI knows your exact deployment procedure
* ✅ AI follows your coding standards automatically
* ✅ Zero time spent explaining procedures—AI has them via MCP
* ✅ 100% consistent code across entire team
* ✅ Workflows auto-update when you change them (no manual sync)
* ✅ AI always uses current, approved procedures
* ✅ Full access to 10 public skills + unlimited custom team skills
**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
`@ulpi/mcp-server-skills`
Runs locally on your machine
Uses your ULPI API key
Keys never leave your machine
Skills update automatically when you modify them
1-hour cache TTL (configurable)
Works with 40+ MCP-compatible AI tools
Claude, 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:
The MCP server requires Node.js 18+ to run.
**Check your version:**
```bash theme={null}
node --version
# Should show v18.0.0 or higher
```
**Install Node.js:**
* **macOS/Linux**: Use [nvm](https://github.com/nvm-sh/nvm) (recommended) or download from [nodejs.org](https://nodejs.org/)
* **Windows**: Download installer from [nodejs.org](https://nodejs.org/)
**Recommended**: Install latest LTS version (currently v22.x)
You need an active ULPI Skills subscription.
**Sign up**: [app.ulpi.io](https://app.ulpi.io)
**Plans**: Starter ($19/mo), Pro ($69/mo), or Enterprise (\$199/mo)
**Free Trial**: 14 days, no credit card required
Connect at least one repository to ULPI to enable tech stack detection.
**How to connect:**
1. Go to [app.ulpi.io/repositories](https://app.ulpi.io/repositories)
2. Click "Connect Repository"
3. Authorize GitHub/GitLab/Bitbucket/Gitea
4. Select repositories to connect
Tech stack detection runs automatically on first connection (takes 1-30 seconds depending on repo size).
Generate an API key with `repo:{id}:skills` scope.
**How to generate:**
1. Go to [app.ulpi.io/api-keys](https://app.ulpi.io/api-keys)
2. Click "Create API Key"
3. Name: "Skills MCP Server"
4. Environment: `live` (production)
5. Scopes: Select `repo:{your_repo_id}:skills`
6. Click "Create"
7. **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:
**Best for**: Most users—no global installation required
**How it works**: `npx` downloads and runs the latest version automatically
**Configuration:**
```json theme={null}
{
"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
**Best for**: Offline use or fixed version control
**Installation:**
```bash theme={null}
npm install -g @ulpi/mcp-server-skills
```
**Configuration:**
```json theme={null}
{
"mcpServers": {
"ulpi-skills": {
"command": "ulpi-mcp-server-skills",
"env": {
"ULPI_API_KEY": "ulpi_live_...",
"ULPI_REPOSITORY_ID": "123"
}
}
}
}
```
**Updating:**
```bash theme={null}
npm update -g @ulpi/mcp-server-skills
```
**Pros**:
* ✅ Faster startup (already installed)
* ✅ Works offline (after initial install)
* ✅ Version control
**Cons**:
* ❌ Manual updates required
* ❌ Installation command needed
**Best for**: Project-specific skill configurations
**Installation:**
```bash theme={null}
cd /path/to/your/project
npm install @ulpi/mcp-server-skills
```
**Configuration:**
```json theme={null}
{
"mcpServers": {
"ulpi-skills": {
"command": "node",
"args": [
"/path/to/your/project/node_modules/@ulpi/mcp-server-skills/dist/index.js"
],
"env": {
"ULPI_API_KEY": "ulpi_live_...",
"ULPI_REPOSITORY_ID": "123"
}
}
}
}
```
**Pros**:
* ✅ Project-specific configuration
* ✅ Version tracked in package.json
* ✅ Team-wide consistency
**Cons**:
* ❌ Must configure per project
* ❌ Longer file path in config
**Best for**: Containerized environments or CI/CD
**Dockerfile:**
```dockerfile theme={null}
FROM node:22-alpine
RUN npm install -g @ulpi/mcp-server-skills
ENV ULPI_API_KEY=""
ENV ULPI_REPOSITORY_ID=""
CMD ["ulpi-mcp-server-skills"]
```
**Build & Run:**
```bash theme={null}
docker build -t ulpi-skills-mcp .
docker run -it \
-e ULPI_API_KEY="ulpi_live_..." \
-e ULPI_REPOSITORY_ID="123" \
ulpi-skills-mcp
```
**Docker Compose:**
```yaml theme={null}
version: '3.8'
services:
ulpi-skills:
image: node:22-alpine
command: npx -y @ulpi/mcp-server-skills
environment:
- ULPI_API_KEY=ulpi_live_...
- ULPI_REPOSITORY_ID=123
restart: unless-stopped
```
**Pros**:
* ✅ Isolated environment
* ✅ Reproducible setup
* ✅ CI/CD friendly
**Cons**:
* ❌ Additional Docker complexity
* ❌ Requires Docker knowledge
***
## IDE-Specific Configuration
Configure MCP server for your AI coding tool:
**Config file location:**
```bash theme={null}
~/Library/Application Support/Claude/claude_desktop_config.json
```
**Create if doesn't exist:**
```bash theme={null}
mkdir -p ~/Library/Application\ Support/Claude
touch ~/Library/Application\ Support/Claude/claude_desktop_config.json
```
```powershell theme={null}
%APPDATA%\Claude\claude_desktop_config.json
```
**Create if doesn't exist:**
```powershell theme={null}
New-Item -ItemType Directory -Force -Path "$env:APPDATA\Claude"
New-Item -ItemType File -Force -Path "$env:APPDATA\Claude\claude_desktop_config.json"
```
```bash theme={null}
~/.config/Claude/claude_desktop_config.json
```
**Create if doesn't exist:**
```bash theme={null}
mkdir -p ~/.config/Claude
touch ~/.config/Claude/claude_desktop_config.json
```
**Add configuration:**
```json theme={null}
{
"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.)
**Config file location:**
```bash theme={null}
~/.cursor/mcp_config.json
```
```powershell theme={null}
%USERPROFILE%\.cursor\mcp_config.json
```
```bash theme={null}
~/.cursor/mcp_config.json
```
**Add configuration:**
```json theme={null}
{
"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 Cursor** for changes to take effect.
**Verify**:
* Open Cursor Settings (`Cmd+,` or `Ctrl+,`)
* Navigate to "MCP Servers"
* Check for "ulpi-skills" with green status indicator
**Config file location:**
```bash theme={null}
~/Library/Application Support/Windsurf/mcp_config.json
```
```powershell theme={null}
%APPDATA%\Windsurf\mcp_config.json
```
```bash theme={null}
~/.config/Windsurf/mcp_config.json
```
**Add configuration:**
```json theme={null}
{
"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 Windsurf** for changes to take effect.
**Extension**: [Continue](https://marketplace.visualstudio.com/items?itemName=Continue.continue)
**Config file location:**
```bash theme={null}
~/.continue/config.json
```
**Add MCP server:**
```json theme={null}
{
"mcpServers": [
{
"name": "ulpi-skills",
"command": "npx",
"args": ["-y", "@ulpi/mcp-server-skills"],
"env": {
"ULPI_API_KEY": "ulpi_live_YOUR_KEY_HERE",
"ULPI_REPOSITORY_ID": "123"
}
}
]
}
```
**Restart VSCode** for changes to take effect.
**Verify**:
* Open Continue extension panel
* Look for "MCP Servers" section
* Check for "ulpi-skills" with connected status
**Extension**: [Cline](https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev)
**Config file location:**
```bash theme={null}
~/.cline/mcp_settings.json
```
**Add MCP server:**
```json theme={null}
{
"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 VSCode** for changes to take effect.
**Config file location:**
```bash theme={null}
~/.config/zed/settings.json
```
**Add MCP configuration:**
```json theme={null}
{
"mcp": {
"servers": {
"ulpi-skills": {
"command": "npx",
"args": ["-y", "@ulpi/mcp-server-skills"],
"env": {
"ULPI_API_KEY": "ulpi_live_YOUR_KEY_HERE",
"ULPI_REPOSITORY_ID": "123"
}
}
}
}
}
```
**Restart Zed** for changes to take effect.
**Config file location:**
```bash theme={null}
~/.config/claude-code/mcp.json
```
**Add configuration:**
```json theme={null}
{
"mcpServers": {
"ulpi-skills": {
"command": "npx",
"args": ["-y", "@ulpi/mcp-server-skills"],
"env": {
"ULPI_API_KEY": "ulpi_live_YOUR_KEY_HERE",
"ULPI_REPOSITORY_ID": "123"
}
}
}
}
```
**Verify:**
```bash theme={null}
claude-code --mcp-status
```
**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](/mcp/tools).
***
## 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](https://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](https://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
```json theme={null}
{
"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:
**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
**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:
1. Create Laravel API Endpoint
2. Laravel Database Migration
3. Write PHPUnit Tests
4. Git Commit Best Practices
5. Database Query Optimization
6. Implement Laravel Queue Job
```
**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
**Ask your AI assistant:**
> "Use the 'Create Laravel API Endpoint' skill to create a /api/users endpoint"
**Expected behavior:**
The AI should:
1. Fetch the skill via MCP
2. Follow the skill's steps
3. Generate code based on the skill workflow
4. 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:
```json theme={null}
{
"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:
```json theme={null}
{
"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
**Problem:** Windows reports `'npx' is not recognized as an internal or external command`
**Cause:** Node.js not installed or not in PATH
**Solution:**
1. Install Node.js from [nodejs.org](https://nodejs.org/)
2. Restart your terminal/IDE
3. Verify: `node --version` and `npx --version`
**Alternative:** Use full path to npx:
```json theme={null}
{
"command": "C:\\Program Files\\nodejs\\npx.cmd",
"args": ["-y", "@ulpi/mcp-server-skills"]
}
```
**Problem:** MCP server returns 401 authentication error
**Cause:** Invalid or expired API key
**Solution:**
1. Verify API key format: `ulpi_live_...` or `ulpi_test_...`
2. Check key hasn't expired (check [app.ulpi.io/api-keys](https://app.ulpi.io/api-keys))
3. Verify key has `repo:{id}:skills` scope
4. Regenerate key if needed
**Problem:** MCP server returns 403 forbidden error
**Cause:** API key doesn't have correct scope
**Solution:**
1. Check API key scopes at [app.ulpi.io/api-keys](https://app.ulpi.io/api-keys)
2. Verify scope includes `repo:{repository_id}:skills`
3. 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
```
**Problem:** API returns 404 for repository
**Cause:** Repository ID doesn't exist or not connected
**Solution:**
1. Verify repository ID at [app.ulpi.io/repositories](https://app.ulpi.io/repositories)
2. Check repository is connected (not just added)
3. 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`
**Problem:** `list_skills` returns no skills
**Cause:** Tech stack not detected or no matching skills
**Solution:**
1. **Check tech stack detection:**
* Go to repository settings
* View "Detected Technologies"
* If empty, trigger detection by pushing a commit
2. **Verify public skills match your tech stack:**
* Public skills filter by tech stack
* If using uncommon tech stack, create custom skills
3. **Check custom skills:**
* Verify custom skills are marked "Active"
* Check tech stack filters on custom skills
4. **Force refresh cache:**
```json theme={null}
"env": {
"ULPI_CACHE_ENABLED": "false"
}
```
**Problem:** IDE/app doesn't show MCP server connection
**Cause:** Configuration file syntax error or wrong location
**Solution:**
1. **Validate JSON syntax:**
* Use [jsonlint.com](https://jsonlint.com/) to check for syntax errors
* Common errors: missing commas, trailing commas, unquoted strings
2. **Verify config file location:**
* Check platform-specific paths (see IDE sections above)
* Ensure file exists: `ls ~/.config/Claude/claude_desktop_config.json`
3. **Restart IDE/app completely:**
* Quit application (don't just close window)
* Restart
* Wait 10 seconds for MCP server to initialize
4. **Check logs:**
* Claude Desktop logs: `~/Library/Logs/Claude/`
* Cursor logs: View → Output → Select "MCP" from dropdown
* VSCode logs: View → Output → Select "Continue" or "Cline"
**Problem:** MCP server slow or times out
**Cause:** Network issues, API rate limiting, or slow cache
**Solution:**
1. **Increase timeout:**
```json theme={null}
"env": {
"ULPI_TIMEOUT": "60000" // 1 minute
}
```
2. **Check internet connection:**
* Test API directly: `curl https://api.ulpi.io/health`
* Verify no firewall blocking API requests
3. **Enable caching:**
```json theme={null}
"env": {
"ULPI_CACHE_ENABLED": "true",
"ULPI_CACHE_TTL": "7200" // 2 hours
}
```
4. **Check API rate limits:**
* View usage at [app.ulpi.io/usage](https://app.ulpi.io/usage)
* Upgrade plan if hitting rate limits
**Problem:** Skill changes not appearing in AI assistant
**Cause:** Cache TTL hasn't expired
**Solution:**
1. **Clear cache manually:**
* Delete cache directory (usually `~/.ulpi/cache/`)
* Restart MCP server
2. **Reduce cache TTL:**
```json theme={null}
"env": {
"ULPI_CACHE_TTL": "300" // 5 minutes
}
```
3. **Disable cache during development:**
```json theme={null}
"env": {
"ULPI_CACHE_ENABLED": "false"
}
```
4. **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:
**No action needed!**
If using `npx`, the latest version is automatically downloaded on each run.
**Force clear npx cache:**
```bash theme={null}
npx clear-npx-cache
npx -y @ulpi/mcp-server-skills --version
```
**Update command:**
```bash theme={null}
npm update -g @ulpi/mcp-server-skills
```
**Check current version:**
```bash theme={null}
ulpi-mcp-server-skills --version
```
**Check latest available version:**
```bash theme={null}
npm view @ulpi/mcp-server-skills version
```
**Update command:**
```bash theme={null}
cd /path/to/your/project
npm update @ulpi/mcp-server-skills
```
**Or upgrade to latest:**
```bash theme={null}
npm install @ulpi/mcp-server-skills@latest
```
**After updating:**
1. Restart your IDE/app
2. Verify version: Check logs or ask AI assistant
3. 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:**
1. Generate new API key at [app.ulpi.io/api-keys](https://app.ulpi.io/api-keys)
2. Update config files with new key
3. Restart MCP servers
4. Verify working
5. Revoke old API key
***
## Next Steps
Start using skills in your AI coding workflow
Build team-specific skills for your unique workflows
Understand the technical architecture behind skills
***
**Need help?** Check our [FAQ](/faq) or contact support at [support@ulpi.io](mailto:support@ulpi.io)