mcp-prompt-optimizer/docs/client-configurations.md

Local MCP server for AI-Enhanced Prompt Optimizer API with context awareness and parameter preservation

# MCP Client Configuration Guide

This guide shows how to configure different MCP clients to use the Prompt Optimizer.

## Prerequisites

1. Install the package: `npm install -g mcp-prompt-optimizer`
2. Set up your API key: `mcp-prompt-optimizer --setup`
3. Have an active Creator or Innovator subscription
4. Ensure backend connectivity: The package connects to `https://p01--project-optimizer--fvrdk8m9k9j.code.run`

## Claude Desktop

### Configuration File Location
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

### Configuration
```json
{
  "mcpServers": {
    "prompt-optimizer": {
      "command": "npx",
      "args": ["mcp-prompt-optimizer"]
    }
  }
}
```

### Usage
1. Restart Claude Desktop after configuration
2. The `optimize_prompt` tool will appear in Claude's available tools
3. Ask Claude to optimize your prompts using the tool

## Cursor IDE

### Configuration File Location
- **All platforms**: `~/.cursor/mcp.json`

### Configuration
```json
{
  "mcpServers": {
    "prompt-optimizer": {
      "command": "npx",
      "args": ["mcp-prompt-optimizer"]
    }
  }
}
```

### Usage
1. Restart Cursor after configuration
2. Access via Cursor's AI features and tool integration
3. The optimizer will be available as a tool in AI conversations

## Windsurf IDE

### Configuration Methods

#### Method 1: Settings UI
1. Open Windsurf Settings
2. Navigate to MCP Servers section
3. Add new server:
   - **Name**: prompt-optimizer
   - **Command**: npx
   - **Args**: mcp-prompt-optimizer

#### Method 2: Configuration File
Location varies by platform, typically in Windsurf's config directory.

```json
{
  "mcpServers": {
    "prompt-optimizer": {
      "command": "npx",
      "args": ["mcp-prompt-optimizer"]
    }
  }
}
```

### Usage
1. Restart Windsurf after configuration
2. Access through Windsurf's AI assistant features
3. Use the tool in AI-powered coding sessions

## Additional MCP Clients

The package is compatible with any MCP-compliant client. For other clients:

### Generic Configuration
```json
{
  "mcpServers": {
    "prompt-optimizer": {
      "command": "npx",
      "args": ["mcp-prompt-optimizer"]
    }
  }
}
```

### Alternative Execution Methods
If `npx` doesn't work, try these alternatives:

#### Direct Node.js execution
```json
{
  "mcpServers": {
    "prompt-optimizer": {
      "command": "node",
      "args": ["/path/to/global/node_modules/mcp-prompt-optimizer/index.js"]
    }
  }
}
```

#### Direct executable (if globally installed)
```json
{
  "mcpServers": {
    "prompt-optimizer": {
      "command": "mcp-prompt-optimizer"
    }
  }
}
```

## Remote Access (HTTP-based Clients)

For clients that support HTTP-based MCP servers, you can use direct API access:

### HTTP Configuration Example
```json
{
  "mcpServers": {
    "prompt-optimizer-remote": {
      "transport": "http",
      "url": "https://p01--project-optimizer--fvrdk8m9k9j.code.run/api/v1/mcp/optimize",
      "headers": {
        "X-API-Key": "your-api-key-here"
      }
    }
  }
}
```

**⚠️ Security Note**: Replace `your-api-key-here` with your actual API key. Be careful not to commit configuration files with API keys to version control.

## Testing Your Configuration

### Method 1: Manual Server Test
```bash
# Start the server manually to test
mcp-prompt-optimizer

# You should see:
# ✅ Connected to Prompt Optimizer API
#    Tier: creator
#    Quota: 5/200 used
#    Status: active
# 🚀 MCP Prompt Optimizer Server running...
```

### Method 2: Backend Connectivity Test
```bash
# Test backend health
curl https://p01--project-optimizer--fvrdk8m9k9j.code.run/health

# Test API key validation
curl -X POST "https://p01--project-optimizer--fvrdk8m9k9j.code.run/api/v1/validate-key" \
     -H "X-API-Key: your-api-key-here"
```

### Method 3: Client Integration Test
1. Open your configured MCP client
2. Try asking the AI to use the `optimize_prompt` tool
3. Example: "Please optimize this prompt: 'write code' using the optimize_prompt tool with goals clarity and specificity"

## Common Configuration Issues

### Issue: "Command not found" or "npx not found"
**Solutions**:
1. Ensure Node.js and npm are installed: `node --version && npm --version`
2. Install package globally: `npm install -g mcp-prompt-optimizer`
3. Check npm global path: `npm config get prefix`
4. Try alternative execution methods (see above)

### Issue: "API key not found"
**Solution**: Run the setup command:
```bash
mcp-prompt-optimizer --setup
```

### Issue: "Connection failed" or "Backend unreachable"
**Solutions**:
1. Check internet connection
2. Test backend manually: `curl https://p01--project-optimizer--fvrdk8m9k9j.code.run/health`
3. Verify API key at [dashboard](https://promptoptimizer-blog.vercel.app/dashboard)
4. Ensure subscription is active
5. Try regenerating API key if necessary

### Issue: "Tool not appearing in client"
**Solutions**:
1. Restart your MCP client completely
2. Check configuration file syntax (JSON must be valid)
3. Verify file path is correct for your platform
4. Check client-specific logs for MCP server errors
5. Test server manually first

### Issue: "Invalid API key format"
**Verification**:
- API keys must start with `sk-opt-`
- Must be obtained from [dashboard](https://promptoptimizer-blog.vercel.app/dashboard)
- Creator or Innovator subscription required

### Issue: "Quota exceeded"
**Solutions**:
1. Check usage at [dashboard](https://promptoptimizer-blog.vercel.app/dashboard)
2. Upgrade subscription if needed
3. Wait for monthly quota reset
4. Contact support for quota adjustments

## Advanced Configuration

### Custom Backend URL
If you need to use a different backend URL (e.g., for testing):

```bash
# Set environment variable
export PROMPT_OPTIMIZER_BACKEND_URL="https://your-custom-backend.com"
mcp-prompt-optimizer

# Or configure permanently
mcp-prompt-optimizer --setup
# Then manually edit ~/.prompt-optimizer/config.json
```

### Multiple API Keys (Team Usage)
For teams using multiple API keys:

1. Each user should install the package individually
2. Configure with their own API key: `mcp-prompt-optimizer --setup`
3. Use separate configuration names if needed:

```json
{
  "mcpServers": {
    "prompt-optimizer-user1": {
      "command": "npx",
      "args": ["mcp-prompt-optimizer"]
    },
    "prompt-optimizer-user2": {
      "command": "npx", 
      "args": ["mcp-prompt-optimizer"]
    }
  }
}
```

### Debug Mode
Enable debug logging for troubleshooting:

```bash
# Set debug environment variable
NODE_ENV=development mcp-prompt-optimizer

# Or set permanently in config
export NODE_ENV=development
```

## Environment Variables

The package respects these environment variables:

- `PROMPT_OPTIMIZER_API_KEY`: Override the stored API key
- `PROMPT_OPTIMIZER_BACKEND_URL`: Override the backend URL  
- `NODE_ENV`: Set to 'development' for additional logging
- `DEBUG`: Set to 'mcp-prompt-optimizer' for detailed debug output

Example usage:
```bash
# Temporary override
PROMPT_OPTIMIZER_API_KEY=sk-opt-your-key mcp-prompt-optimizer

# Development mode with debug
NODE_ENV=development DEBUG=mcp-prompt-optimizer mcp-prompt-optimizer
```

## Performance Optimization

### Connection Timeouts
The default timeout is 30 seconds. For slower connections:

```bash
# Increase timeout (not directly configurable, contact support if needed)
```

### Caching
The package automatically caches:
- API key validation results (5 minutes)
- Backend health status (1 minute)
- Configuration file (persistent)

## Support

If you encounter configuration issues:

1. **First Steps**:
   - Check the [troubleshooting section](../README.md#troubleshooting) in the main README
   - Test backend connectivity manually
   - Verify subscription status at [dashboard](https://promptoptimizer-blog.vercel.app/dashboard)

2. **Gather Information**:
   - MCP client type and version
   - Operating system
   - Node.js version (`node --version`)
   - Package version (`npm list -g mcp-prompt-optimizer`)
   - Error messages from client logs

3. **Contact Support**:
   - [Support Portal](https://promptoptimizer-blog.vercel.app/support)
   - [GitHub Issues](https://github.com/prompt-optimizer/mcp-prompt-optimizer/issues)
   - Include gathered information above

## Security Best Practices

### Configuration File Security
- Configuration files may contain sensitive API keys
- Never commit configuration files with API keys to version control
- Use environment variables for CI/CD environments
- Regularly rotate API keys for enhanced security

### API Key Management
- Store keys in local configuration only: `~/.prompt-optimizer/config.json`
- Use different keys for different environments (dev/prod)
- Monitor API key usage in dashboard
- Revoke compromised keys immediately

### Network Security
- All communication uses HTTPS encryption
- Backend hosted on enterprise-grade Northflank infrastructure
- API keys transmitted securely via HTTP headers
- No sensitive data cached in transit

## Client-Specific Notes

### Claude Desktop
- Configuration changes require full restart
- Tool appears in Claude's tool panel
- Supports all optimization goals
- Real-time quota display in responses

### Cursor IDE
- Integrates with Cursor's AI chat features
- Available in code generation contexts
- Supports inline prompt optimization
- Works with Cursor's composer feature

### Windsurf IDE
- Available in AI assistant sidebar
- Integrates with coding workflows
- Supports prompt refinement for code generation
- Compatible with Windsurf's agent features

---

**Backend Infrastructure**: Powered by FastAPI on Northflank  
**Last Updated**: June 2025  
**API Version**: v1 (compatible with backend v0.2.2+)