Commands

How Commands Work

Commands flip the communication direction - instead of the agent asking you, you can proactively send instructions to the agent.

1. You send an SMS to your agent's phone number
2. Agent polls for new commands using get_pending_commands
3. Agent receives and processes your command

Checking for Commands

Use the get_pending_commands tool to check for new commands:

const result = await mcp.callTool("get_pending_commands", {});

// Returns:
{
  commands: [
    {
      id: "cmd_abc123",
      message: "Run the test suite",
      received_at: "2026-01-02T10:30:00Z"
    }
  ]
}

Example Workflow

Here's how an agent might poll for and handle commands:

// Periodically check for commands
async function checkForCommands() {
  const result = await mcp.callTool("get_pending_commands", {});

  for (const command of result.commands) {
    console.log("Received command:", command.message);

    // Process the command
    if (command.message.includes("run tests")) {
      await runTestSuite();
    } else if (command.message.includes("deploy")) {
      await deployToProduction();
    }

    // Notify completion
    await mcp.callTool("send_notification", {
      message: `Completed: ${command.message}`
    });
  }
}

Use Cases

• -Remote triggering - Start tasks from your phone
• -Emergency stops - Send "STOP" to halt operations
• -Parameter updates - Change settings on the fly
• -Status requests - Ask for current status anytime

Best Practices

• 1.Poll reasonably - Don't spam the API, check every few minutes
• 2.Acknowledge commands - Send a notification when you receive and process a command
• 3.Handle unknown commands - Gracefully ignore or ask for clarification
• 4.Document your commands - Let users know what commands are available