> ## Documentation Index
> Fetch the complete documentation index at: https://icepick.hatchet.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Developing Agents

> Instructions for best practices while developing agents.

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:

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm i -g @hatchet-dev/icepick-cli
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={null}
    pnpm i -g @hatchet-dev/icepick-cli
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn global add @hatchet-dev/icepick-cli
    ```
  </Tab>
</Tabs>

## Quick Setup

The basic Icepick MCP server configuration:

```json theme={null}
{
  "mcpServers": {
    "icepick": {
      "command": "icepick",
      "args": ["mcp"]
    }
  }
}
```

## Environment Configuration

### Cursor

Create a `.cursor/mcp.json` file in your project root:

```json theme={null}
{
  "mcpServers": {
    "icepick": {
      "command": "icepick",
      "args": ["mcp"]
    }
  }
}
```

### VS Code

Create a `.vscode/mcp.json` file in your project root:

```json theme={null}
{
  "mcpServers": {
    "icepick": {
      "command": "icepick",
      "args": ["mcp"]
    }
  }
}
```

### Claude Code

Create a `.mcp.json` file in your project root:

```json theme={null}
{
  "mcpServers": {
    "icepick": {
      "command": "icepick",
      "args": ["mcp"]
    }
  }
}
```

Alternatively, configure via the Claude Code CLI:

```bash theme={null}
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:

```json theme={null}
{
  "mcpServers": {
    "icepick": {
      "command": "icepick",
      "args": ["mcp"]
    }
  }
}
```

### Working Directory

Specify a custom working directory:

```json theme={null}
{
  "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:

```bash theme={null}
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.

```sh theme={null}
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.

```sh theme={null}
icepick add tool my-tool
```