APM Logo

Your First MCP Server: The Peon Work Bot

Let's build a fun MCP server that plays a sound effect whenever a task is created in APM. This guide will walk you through creating the server, connecting it to APM, and testing it out.

What We'll Build

A Ruby MCP server called "Peon Server" that:

  • Listens for the apm_task_created tool call from APM
  • Plays a "Work Work" sound effect (like the Warcraft peon!)
  • Responds with "Zug Zug" to confirm it received the task

Prerequisites

  • Ruby 3.0 or later
  • APM running on macOS
  • A sound file named PeonWorkWork.wav (or any .wav file you'd like to use)
  • The Ruby MCP gem: gem install mcp

Step 1: Create the MCP Server

Create a new file called peon_server.rb:

#!/usr/bin/env ruby
require "mcp"
require "mcp/transports/stdio"

class ApmTaskCreated < MCP::Tool
  description "A tool that plays the PeonWorkWork.wav sound file when a task is started"
  input_schema(
    properties: {
      task: {
        type: "object",
        properties: {
          id: { type: "string" },
          name: { type: "string" },
          description: { type: "string" }
        }
      }
    },
    required: ["task"]
  )

  class << self
    def call(task: nil, server_context:)
      sound_file = File.expand_path("../PeonWorkWork.wav", __FILE__)

      system("afplay '#{sound_file}'")

      MCP::Tool::Response.new([{
        type: "text",
        text: "Zug Zug"
      }])
    end
  end
end

# Set up the server
server = MCP::Server.new(
  name: "peon_server",
  tools: [ApmTaskCreated],
)

# Create and start the transport
transport = MCP::Transports::StdioTransport.new(server)
transport.open

Step 2: Add Your Sound File

Place your PeonWorkWork.wav file in the same directory as peon_server.rb. The server expects it to be in the parent directory relative to the script.

If you don't have a Warcraft peon sound, you can:

  1. Use any .wav file and rename it
  2. Or modify the sound_file path in the code to point to your sound file
  3. On macOS, you can use system sounds: /System/Library/Sounds/Glass.aiff

Step 4: Connect the Peon Server to APM

  1. In APM, go to MCP Explorer (press ⌘+5)
  2. Click "Add Server"
  3. Fill in the command to run your server, something like ruby /full/path/to/peon_server.rb and click "Connect"
  4. The Peon server should appear in your server list with a green connection indicator

If the server shows as disconnected:

  • Check that Ruby is in your PATH: which ruby
  • Verify the path to peon_server.rb is correct
  • Look for error messages in APM's console

Step 6: Configure APM to Call Our Tool

Now we need to tell APM to call our apm_task_created tool whenever a task is created. This happens automatically when APM detects a tool with this specific name.

⚠️

Make sure the tool name is exactly apm_task_created - APM looks for this specific name to trigger the tool on task creation events.

Step 7: Test It Out!

Time to hear our peon get to work:

  1. Go to the Projects tab in APM (⌘+1)
  2. Select or create a project
  3. Click "Add Task"
  4. Fill in the task details:
    • Title: "Build more farms" (or anything you like)
    • Description: "We need more food for the war effort"
  5. Click "Create Task"

You should hear your sound effect play! 🔊

Check the MCP Explorer to see the tool execution:

  • The server should show it received the tool call
  • You'll see "Zug Zug" in the response

Understanding the Parameters

When APM calls our tool, it sends a task object with these properties:

task: {
  id: "task_abc123",           # Unique task ID
  name: "Build more farms",    # The task title
  description: "We need..."    # The task description
}

Our server receives this data and can use it however we want. In this example, we just play a sound, but you could:

  • Log task details to a file
  • Mirror the task in JIRA or Linear
  • Enhance the task details with AI and update the description
  • Send notifications to Slack
  • Update a dashboard
  • Trigger other automations
  • Create an Action in APM for a user to review

Troubleshooting

No Sound Playing?

  1. Check volume: Make sure your Mac's volume is up
  2. Test the sound file: Try afplay PeonWorkWork.wav in Terminal
  3. File path: Ensure the .wav file is in the correct location
  4. Permissions: The script needs permission to play sounds

Server Not Receiving Events?

  1. Check MCP server status: Ensure APM's MCP server is running (⌘+6)
  2. Tool name: Must be exactly apm_task_created
  3. Connection status: Server should show green in MCP Explorer
  4. Console logs: Check APM's console for error messages

Ruby Errors?

  1. Install the gem: gem install mcp
  2. Ruby version: Ensure you have Ruby 3.0+: ruby --version
  3. Path issues: Use full paths if relative paths aren't working

Next Steps

Now that you have a working MCP server, try enhancing it:

  1. Different sounds for different task types:

    if task[:name].downcase.include?("urgent")
  system("afplay 'UrgentTask.wav'")
elsif task[:name].downcase.include?("bug")
  system("afplay 'BugAlert.wav'")
end

  2. Log tasks to a file:

    File.open("task_log.txt", "a") do |f|
  f.puts "[#{Time.now}] New task: #{task[:name]}"
end

Conclusion

Congratulations! You've built your first MCP server that integrates with APM. This simple example demonstrates the power of MCP - with just a few lines of Ruby, you've created a server that reacts to events in APM in real-time.

The pattern you've learned here can be applied to build much more sophisticated integrations:

  • Send tasks to external project management tools
  • Trigger CI/CD pipelines when certain tasks are created
  • Update time tracking systems
  • Send notifications to team chat
  • And much more!

Was this page helpful?