Caramelo.dev MCP Server

This is an MCP (Model Context Protocol) server implementation for Caramelo.dev API. It allows AI assistants like Claude and Cursor to interact with your Caramelo.dev application using the MCP protocol.

Quick Start

The easiest way to use the Caramelo.dev MCP server is via NPX - no installation required!

Get Your API Token

1. Go to your Caramelo.dev settings
2. Generate an MCP API token
3. Copy the token (it starts with user_ or org_)

Add to Your MCP Client

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "caramelo": {
      "command": "npx",
      "args": ["caramelo-mcp-server", "--token", "YOUR_TOKEN_HERE"]
    }
  }
}

Cursor

Add to your ~/.cursor/mcp.json:

{
  "caramelo": {
    "command": "npx", 
    "args": ["caramelo-mcp-server", "--token", "YOUR_TOKEN_HERE"]
  }
}

VS Code

Add to your .vscode/mcp.json:

{
  "mcpServers": {
    "caramelo": {
      "command": "npx",
      "args": ["caramelo-mcp-server", "--token", "YOUR_TOKEN_HERE"]
    }
  }
}

Development Usage

If you're developing with a local Caramelo.dev instance, specify a custom URL:

{
  "caramelo-dev": {
    "command": "npx",
    "args": [
      "caramelo-mcp-server",
      "--token", "YOUR_TOKEN_HERE",
      "--url", "https://your-ngrok-url.ngrok-free.app/mcp"
    ]
  }
}

Cloudflare Access Protected Environments

If your Caramelo.dev instance is protected by Cloudflare Access, you can provide the required credentials via environment variables:

{
  "caramelo-staging": {
    "command": "npx",
    "args": [
      "caramelo-mcp-server",
      "--token", "YOUR_TOKEN_HERE",
      "--url", "https://staging.caramelo.dev/mcp"
    ],
    "env": {
      "CF_ACCESS_CLIENT_ID": "your-client-id.access",
      "CF_ACCESS_CLIENT_SECRET": "your-client-secret"
    }
  }
}

The server will automatically include the CF-Access-Client-Id and CF-Access-Client-Secret headers when both environment variables are present. If either is missing, the headers will be omitted (allowing the server to work with non-CF-protected endpoints).

Available Tools

The MCP server provides access to:

• list_repositories - List all repositories you have access to
• list_available_tools - List all available MCP tools

Local Development

If you want to run the server locally for development:

cd mcp_client
npm install
npm run build

# Test production mode
node dist/index.js --token your_token_here

# Test development mode  
node dist/index.js --token your_token_here --url http://localhost:3000/mcp