> ## Documentation Index
> Fetch the complete documentation index at: https://codegeninc-codegen-cg-18858-codegen-mcp-documentation.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Context Protocol (MCP)

> Integrate Codegen with AI editors like Cursor using the Model Context Protocol

# Model Context Protocol (MCP)

The Model Context Protocol (MCP) is an open standard that enables AI applications to securely connect to external data sources and tools. Codegen provides an MCP server that allows AI editors like Cursor to access Codegen's powerful codemod generation and SDK capabilities directly within your development workflow.

## What is MCP?

MCP acts as a bridge between AI assistants and external tools, allowing them to:

* Access external data sources and APIs
* Execute tools and commands safely
* Provide rich context to improve AI responses
* Maintain security through standardized protocols

With Codegen's MCP integration, your AI editor can:

* Generate codemods using the Codegen SDK
* Access Codegen documentation and examples
* Get expert guidance on Codegen best practices
* Streamline your code transformation workflows

## Prerequisites

Before setting up the MCP server, ensure you have:

1. **Codegen CLI installed**: Install via pip or your preferred package manager
   ```bash
   pip install codegen
   ```

2. **Authentication**: Log in to your Codegen account
   ```bash
   codegen login
   ```

3. **AI Editor with MCP support**: Currently supported editors include:
   * [Cursor](https://cursor.com) (recommended)
   * [Claude Desktop](https://claude.ai/desktop)
   * [Cline](https://github.com/cline/cline) (VS Code extension)

## Quick Start

### 1. Start the MCP Server

The easiest way to start the Codegen MCP server is using the built-in CLI command:

```bash
codegen mcp
```

This starts the server with default settings (stdio transport). For additional options:

```bash
# Start with verbose logging
codegen mcp --verbose

# Start with HTTP transport on a specific port
codegen mcp --transport http --port 8080

# View all available options
codegen mcp --help
```

### 2. Configure Your AI Editor

The configuration depends on your AI editor. See the sections below for specific setup instructions.

## Cursor Configuration

Cursor provides the most seamless MCP integration experience. Follow these steps:

### Method 1: Using Cursor Settings (Recommended)

1. **Open Cursor Settings**
   * Press `Cmd/Ctrl + ,` to open settings
   * Navigate to **Features** → **MCP Servers**

2. **Add New MCP Server**

   * Click "Add New MCP Server"
   * Fill in the following details:

   ```
   Name: codegen-mcp
   Type: Command
   Command: codegen mcp
   ```

3. **Save and Restart**
   * Click "Save"
   * Restart Cursor to activate the MCP server

### Method 2: Manual Configuration File

If you prefer manual configuration, you can edit Cursor's MCP configuration file directly:

1. **Locate the configuration file**:
   * **macOS**: `~/Library/Application Support/Cursor/User/mcp_servers.json`
   * **Windows**: `%APPDATA%\Cursor\User\mcp_servers.json`
   * **Linux**: `~/.config/Cursor/User/mcp_servers.json`

2. **Add the Codegen MCP server**:
   ```json
   {
     "mcpServers": {
       "codegen-mcp": {
         "command": "codegen",
         "args": ["mcp"]
       }
     }
   }
   ```

3. **Restart Cursor** to load the new configuration.

### Verification

To verify the MCP server is working in Cursor:

1. Open a new chat in Cursor
2. Look for "Available Tools" in the chat interface
3. You should see Codegen MCP tools listed, such as:
   * `generate_codemod`
   * `ask_codegen_sdk`
   * `improve_codemod`

## Alternative Editors

### Claude Desktop

For Claude Desktop, add this configuration to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "codegen-mcp": {
      "command": "codegen",
      "args": ["mcp"]
    }
  }
}
```

**Configuration file locations**:

* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

### Cline (VS Code Extension)

For the Cline VS Code extension, add this to your `cline_mcp_settings.json`:

```json
{
  "mcpServers": {
    "codegen-mcp": {
      "command": "codegen",
      "args": ["mcp"]
    }
  }
}
```

## Available Tools

Once configured, the Codegen MCP server provides these tools to your AI editor:

### `generate_codemod`

Generate a new codemod for a specific task and codebase.

**Parameters**:

* `title`: The title of the codemod (hyphenated format)
* `task`: Description of what the codemod should accomplish
* `codebase_path`: Absolute path to your codebase directory

**Example usage in chat**:

```
Generate a codemod called "add-logging" that adds console.log statements to all functions in my React components at /path/to/my/project
```

### `ask_codegen_sdk`

Get expert guidance on any aspect of the Codegen SDK.

**Parameters**:

* `query`: Your question about the Codegen SDK

**Example usage in chat**:

```
How do I use the Codebase class to analyze TypeScript files?
```

### `improve_codemod`

Improve an existing codemod based on feedback and concerns.

**Parameters**:

* `codemod_source`: The source code of the codemod to improve
* `task`: The original task description
* `concerns`: List of issues discovered with the current codemod
* `context`: Additional context and related files
* `language`: Programming language (e.g., PYTHON, TYPESCRIPT)

## Authentication

The MCP server uses your existing Codegen authentication. Ensure you're logged in:

```bash
# Check current authentication status
codegen profile

# Log in if needed
codegen login
```

If you encounter authentication issues:

1. **Verify your login status**: `codegen profile`
2. **Re-authenticate if needed**: `codegen logout && codegen login`
3. **Check your API token**: Ensure your token hasn't expired

## Troubleshooting

### Common Issues

**MCP Server Not Starting**

* Verify Codegen is properly installed: `codegen --version`
* Check authentication: `codegen profile`
* Try running with verbose logging: `codegen mcp --verbose`

**Tools Not Appearing in Editor**

* Restart your AI editor after configuration changes
* Check the MCP server configuration syntax
* Verify the `codegen` command is in your system PATH

**Permission Errors**

* Ensure the `codegen` command is executable
* Check file permissions on configuration files
* Try running the editor with appropriate permissions

**Path Resolution Issues**

* Use absolute paths in configuration when possible
* Verify the `codegen` command location: `which codegen`
* Consider using the full path to the codegen executable

### Advanced Configuration

**Custom Server Path**
If you need to specify a custom path to the Codegen installation:

```json
{
  "mcpServers": {
    "codegen-mcp": {
      "command": "/path/to/your/codegen",
      "args": ["mcp"]
    }
  }
}
```

**Environment Variables**
You can set environment variables for the MCP server:

```json
{
  "mcpServers": {
    "codegen-mcp": {
      "command": "codegen",
      "args": ["mcp", "--verbose"],
      "env": {
        "CODEGEN_API_URL": "https://api.codegen.com",
        "CODEGEN_MCP_VERBOSE": "1"
      }
    }
  }
}
```

**HTTP Transport**
For remote or multi-user setups, you can use HTTP transport:

```bash
# Start server with HTTP transport
codegen mcp --transport http --port 8080
```

Then configure your editor to connect to the HTTP endpoint instead of using the command interface.

## Best Practices

1. **Keep Codegen Updated**: Regularly update to get the latest MCP features
   ```bash
   codegen update
   ```

2. **Use Descriptive Codemod Names**: Use clear, hyphenated names for generated codemods
   ```
   Good: "add-error-handling", "migrate-to-hooks"
   Avoid: "fix", "update", "change"
   ```

3. **Provide Clear Task Descriptions**: Be specific about what you want the codemod to accomplish
   ```
   Good: "Add try-catch blocks around all async function calls in React components"
   Avoid: "Add error handling"
   ```

4. **Test Generated Codemods**: Always review and test generated codemods before applying them to production code

5. **Use Version Control**: Commit your code before running codemods to easily revert if needed

## Examples

### Example 1: Generate a React Hook Migration Codemod

In your AI editor chat:

```
Use the generate_codemod tool to create a codemod called "migrate-class-to-hooks" that converts React class components to functional components with hooks. The codebase is located at /Users/myname/projects/my-react-app
```

### Example 2: Get SDK Help

```
Use ask_codegen_sdk to explain how to use the FileAnalyzer class to detect unused imports in Python files
```

### Example 3: Improve an Existing Codemod

```
I have a codemod that's not working correctly. Use improve_codemod to fix it. The codemod source is: [paste your codemod code]. The task was to add TypeScript types to function parameters, but it's missing some edge cases for arrow functions and async functions.
```

## Support

If you encounter issues with the MCP integration:

1. **Check the documentation**: Review this guide and the [official MCP documentation](https://modelcontextprotocol.io/)
2. **Enable verbose logging**: Use `codegen mcp --verbose` for detailed error information
3. **Community support**: Join our [Discord community](https://discord.gg/codegen) for help
4. **Report bugs**: Create an issue on our [GitHub repository](https://github.com/codegen-sh/codegen)

## What's Next?

With Codegen MCP integration set up, you can:

* Generate codemods directly from your AI editor
* Get instant help with Codegen SDK questions
* Streamline your code transformation workflows
* Iterate quickly on codemod improvements

Explore our [SDK documentation](/introduction/api) to learn more about Codegen's capabilities, or check out our [examples repository](https://github.com/codegen-sh/codegen-examples) for inspiration.