When developing Icepick agents, it’s recommended to use the Icepick MCP server for local development. This allows for fast scaffolding of agents and tools, and provides instructions with best practices for agent development.

​
Icepick MCP Server

The Icepick CLI comes bundled with a local MCP server which runs on a stdio connection for development. This enables AI development tools to interact with your Icepick project programmatically. Make sure you have installed the Icepick CLI globally: 
npm i -g @hatchet-dev/icepick-cli

​
Quick Setup

The basic Icepick MCP server configuration: 
{
  "mcpServers": {
    "icepick": {
      "command": "icepick",
      "args": ["mcp"]
    }
  }
}

​
Environment Configuration

​
Cursor

Create a .cursor/mcp.json file in your project root: 
{
  "mcpServers": {
    "icepick": {
      "command": "icepick",
      "args": ["mcp"]
    }
  }
}

​
VS Code

Create a .vscode/mcp.json file in your project root: 
{
  "mcpServers": {
    "icepick": {
      "command": "icepick",
      "args": ["mcp"]
    }
  }
}

​
Claude Code

Create a .mcp.json file in your project root: 
{
  "mcpServers": {
    "icepick": {
      "command": "icepick",
      "args": ["mcp"]
    }
  }
}
Alternatively, configure via the Claude Code CLI: 
claude-code config mcp add icepick "icepick mcp"

​
Other AI Tools

For tools that support MCP, place the configuration in their designated MCP configuration file location. The standard configuration format remains: 
{
  "mcpServers": {
    "icepick": {
      "command": "icepick",
      "args": ["mcp"]
    }
  }
}

​
Working Directory

Specify a custom working directory: 
{
  "mcpServers": {
    "icepick": {
      "command": "icepick",
      "args": ["mcp", "--cwd", "/path/to/your/icepick/project"]
    }
  }
}

​
Troubleshooting

​
Common Issues

MCP server not starting: Ensure Icepick CLI is installed and accessible: 
icepick --version
Permission errors: Check that the Icepick CLI has execution permissions and the project directory is accessible. Connection failures: Verify the configuration file is in the correct location for your environment and follows the proper JSON format.

​
Using the CLI

You can also use the Icepick CLI for development using the icepick add commands. These commands generate the boilerplate for agents and tools in a default Icepick project structure. You can also use these as a starting point for agents in your own project.

​
Creating an Agent

You can scaffold a new agent using the icepick add agent command. This command creates a new agent with the specified name and model, and generates the boilerplate code for the agent in the ./src/agents directory. 
icepick add agent my-agent

​
Creating a Tool

You can scaffold a new tool using the icepick add tool command. This command creates a new tool with the specified name and category, and generates the boilerplate code for the tool in the ./src/tools directory. 
icepick add tool my-tool