Getting Started

Install Anvil and create your first tool definition in under 2 minutes.

Installation

npm install -g @anvil-tools/cli

Verify:

anvil --version  # 0.4.0

Create a Project

anvil init my-tools
cd my-tools

This creates:

  • tools.anvil.yaml — your tool definitions
  • anvil.config.ts — optional compiler configuration

Define a Tool

Edit tools.anvil.yaml:

anvil: "1.0"

service:
  name: my-tools
  version: "1.0.0"

tools:
  greet:
    description: Greet someone by name
    agent:
      description: Use this tool to generate a personalized greeting.
      when_to_use:
        - User asks for a greeting
    parameters:
      name:
        type: string
        required: true
        description: The name to greet
    returns:
      type: object
      properties:
        message:
          type: string
          description: The greeting message
    side_effects: none
    cost: free
    examples:
      - name: basic
        input: { name: "World" }
        output: { message: "Hello, World!" }
        prompt: "Say hello to the world"

Compile

No config file needed — targets are built into the CLI:

anvil compile --target mcp                # MCP server
anvil compile --target mcp,docs           # MCP + documentation
anvil compile --target anthropic          # Claude API format
anvil compile --all                       # all 10 targets

Output goes to out/ by default.

Run as MCP Server

Start an MCP server directly from your YAML — no compile step needed:

anvil serve --stub tools.anvil.yaml

This starts a production MCP server (using @modelcontextprotocol/sdk) that returns example data from your definitions. Works with any MCP client.

Connect to Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "my-tools": {
      "command": "npx",
      "args": ["@anvil-tools/cli", "serve", "--stub", "tools.anvil.yaml"]
    }
  }
}

Connect to Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "my-tools": {
      "command": "npx",
      "args": ["@anvil-tools/cli", "serve", "--stub", "./tools.anvil.yaml"]
    }
  }
}

Validate and Check

anvil validate          # check for errors
anvil doctor            # project health check with recommendations

What's Next