MCP Server: heka-campaign-admin

Heka exposes an MCP (Model Context Protocol) server that allows AI agents (Claude Code, Codex, etc.) to manage campaign phases and resources programmatically.

Architecture

Claude Code ──stdio──► heka-campaign-admin (FastMCP)
                              │
                              ├─ subprocess ──► heka CLI
                              │                    │
                              │                    └──► Heka Server (HTTP)
                              │
                              └─ Environment vars:
                                   HEKA_ADMIN_BASE_URL
                                   HEKA_ADMIN_TOKEN

The MCP server wraps the heka CLI as subprocess calls. Each tool invokes a CLI subcommand and returns parsed JSON.

Setup

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "heka-campaign-admin": {
      "command": "uv",
      "args": ["run", "python", "-m", "heka.mcp.campaign_admin"],
      "env": {
        "HEKA_ADMIN_BASE_URL": "https://heka-operator.fly.dev",
        "HEKA_ADMIN_TOKEN": "your-jwt-token"
      }
    }
  }
}

Available tools

heka_campaign_phase_update

Update a campaign phase's agent instructions.

Parameter	Type	Required	Description
campaign_id	string	yes	Campaign identifier
phase_id	string	yes	Phase identifier
instructions	string	yes	New agent instructions

Example usage by an AI agent:

Update the qualification phase instructions to ask about the child's age
and preferred class schedule before suggesting a trial class.

heka_campaign_resource_list

List all resources in a campaign context.

Parameter	Type	Required	Description
campaign_id	string	yes	Campaign identifier

heka_campaign_resource_add

Add a resource to a campaign context.

Parameter	Type	Required	Description
campaign_id	string	yes	Campaign identifier
resource_id	string	yes	Unique resource ID
title	string	yes	Resource title
content	string	yes	Text content
media_url	string	no	Pre-hosted media URL
media_type	string	no	Media type hint

heka_campaign_resource_update

Update fields on an existing campaign resource. At least one optional field must be provided.

Parameter	Type	Required	Description
campaign_id	string	yes	Campaign identifier
resource_id	string	yes	Resource ID to update
title	string	no	New title
content	string	no	New content
media_url	string	no	New media URL
media_type	string	no	New media type

heka_campaign_resource_delete

Delete a resource from a campaign context.

Parameter	Type	Required	Description
campaign_id	string	yes	Campaign identifier
resource_id	string	yes	Resource ID to delete

Error handling

Tools raise RuntimeError with the CLI's stderr output when:

• The heka CLI exits with a nonzero code
• The CLI returns non-JSON output
• The subprocess times out (30s default)

Limitations

• No media file upload — the MCP server only supports media_url, not local file uploads (subprocess can't forward multipart from MCP protocol)
• Subprocess overhead — each tool call spawns a heka CLI subprocess. For bulk operations, use the REST API directly
• Authentication — the MCP server forwards HEKA_ADMIN_BASE_URL and HEKA_ADMIN_TOKEN from its environment to the CLI subprocess