MCP Client Setup

This guide shows you how to configure the Cosmic MCP Server with various MCP-compatible clients.

Prerequisites

Before setting up the MCP server with any client, you'll need:

1. Cosmic Account: Sign up at cosmicjs.com
2. Cosmic Bucket: Create a bucket and note down your credentials
3. API Keys: Get your Read and Write keys from Bucket Settings → API Keys

VS Code (Claude Dev Extension)

Installation

1. Install the Claude Dev extension from the VS Code marketplace
2. Configure the MCP server in your VS Code settings

Configuration

Add this configuration to your VS Code settings JSON (settings.json):

{
  "mcp": {
    "servers": {
      "Cosmic": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "cosmic-mcp"],
        "env": {
          "COSMIC_BUCKET_SLUG": "your-bucket-slug",
          "COSMIC_READ_KEY": "your-read-key",
          "COSMIC_WRITE_KEY": "your-write-key",
          "DEBUG": "false"
        }
      }
    }
  }
}

Usage

1. Open the Command Palette (Cmd/Ctrl + Shift + P)
2. Run "Claude Dev: Start New Chat"
3. The Cosmic MCP tools will be available in your conversation

Cursor

Configuration

Create or update the .cursor/mcp.json file in your project root:

{
  "mcpServers": {
    "Cosmic": {
      "command": "npx",
      "args": ["-y", "cosmic-mcp"],
      "env": {
        "COSMIC_BUCKET_SLUG": "your-bucket-slug",
        "COSMIC_READ_KEY": "your-read-key",
        "COSMIC_WRITE_KEY": "your-write-key",
        "DEBUG": "false"
      }
    }
  }
}

Usage

1. Open Cursor
2. Start a new chat with Claude
3. The Cosmic MCP tools will be automatically available

Local Development Setup

If you're developing locally or want to use a specific version of the MCP server:

Building from Source

# Clone the repository
git clone https://github.com/patgpt/cosmic-mcp.git
cd cosmic-mcp

# Install dependencies
bun install

# Build the project
bun run build

# The server will be available at ./dist/server.js

VS Code Configuration (Local)

{
  "mcp": {
    "servers": {
      "Cosmic": {
        "type": "stdio",
        "command": "node",
        "args": ["/path/to/cosmic-mcp/dist/server.js"],
        "env": {
          "COSMIC_BUCKET_SLUG": "your-bucket-slug",
          "COSMIC_READ_KEY": "your-read-key",
          "COSMIC_WRITE_KEY": "your-write-key",
          "DEBUG": "true"
        }
      }
    }
  }
}

Cursor Configuration (Local)

{
  "mcpServers": {
    "Cosmic": {
      "command": "node",
      "args": ["/path/to/cosmic-mcp/dist/server.js"],
      "env": {
        "COSMIC_BUCKET_SLUG": "your-bucket-slug",
        "COSMIC_READ_KEY": "your-read-key",
        "COSMIC_WRITE_KEY": "your-write-key",
        "DEBUG": "true"
      }
    }
  }
}

Environment Variables

Variable	Description	Required
COSMIC_BUCKET_SLUG	Your Cosmic bucket slug	Yes
COSMIC_READ_KEY	Your Cosmic read key	Yes
COSMIC_WRITE_KEY	Your Cosmic write key	Yes
DEBUG	Enable debug logging (true/false)	No

Troubleshooting

Common Issues

Server not starting:

• Ensure all environment variables are set correctly
• Check that your Cosmic API keys are valid
• Verify network connectivity to Cosmic API

Tools not appearing:

• Restart your MCP client
• Check the client logs for error messages
• Verify the MCP server configuration syntax

Permission errors:

• Ensure your Cosmic Write Key has the necessary permissions
• Check that your bucket exists and is accessible

Debug Mode

Enable debug mode by setting DEBUG=true in your environment variables. This will provide detailed logging information to help diagnose issues.

Logs

Check the following locations for logs:

• VS Code: Open the Output panel and select "Claude Dev"
• Cursor: Check the developer console (Cmd/Ctrl + Shift + I)
• Server logs: Available in the terminal when running locally

Next Steps

Once you have the MCP server configured:

1. Explore the available tools
2. Learn about configuration options
3. Check out the API documentation

Support

If you encounter issues:

1. Check the troubleshooting section
2. Review the GitHub issues
3. Create a new issue with detailed information about your setup