planexeorg/planexe-mcp

PlanExe MCP Skill

Access PlanExe's powerful planning capabilities directly from OpenClaw via the Model Context Protocol (MCP).

Overview

The planexe-mcp skill provides a unified interface to interact with PlanExe across three deployment scenarios:

• Cloud: mcp.planexe.org (Stripe credits at home.planexe.org)
• Remote Docker: Container on a separate machine
• Local Docker: Container on the same machine as OpenClaw

Setup by Deployment Scenario

Scenario A: Cloud-Hosted Service

Connect to the hosted PlanExe MCP service.

Configuration:

Add to your OpenClaw config or environment:

PLANEXE_MCP_URL=https://mcp.planexe.org
PLANEXE_API_KEY=your_api_key_from_planexe_account

How to Get Your API Key:

1. Visit home.planexe.org
2. Purchase credits via Stripe
3. Generate an API key in your account dashboard
4. Copy the key to your OpenClaw configuration

---

Scenario B: Remote Docker

Run PlanExe in Docker on a separate machine and connect remotely.

On the Remote Machine:

docker run -p 8001:8001 planexe/planexe:latest

Configuration in OpenClaw:

PLANEXE_MCP_URL=http://<remote-ip>:8001
PLANEXE_API_KEY=your_api_key

Replace <remote-ip> with your remote machine's IP address or hostname.

---

Scenario C: Local Docker

Run PlanExe in Docker on the same machine as OpenClaw.

Setup:

docker run -p 8001:8001 planexe/planexe:latest

Configuration in OpenClaw:

PLANEXE_MCP_URL=http://127.0.0.1:8001
PLANEXE_API_KEY=your_api_key

---

Invoking PlanExe Tools

The PlanExe MCP exposes nine core tools via the /mcp endpoint:

Tool 1: example_plans

Preview curated example plans with download links for reports and zip bundles.

No parameters required:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "example_plans",
    "arguments": {}
  }
}

Returns: List of example plans with title, report_url, and zip_url.

---

Tool 2: example_prompts

Get example prompts to understand what PlanExe can do.

No parameters required:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "example_prompts",
    "arguments": {}
  }
}

Returns: List of example prompts for planning tasks.

---

Tool 3: plan_create

Create a new planning task. This is the main entry point for generating plans.

Parameters:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "plan_create",
    "arguments": {
      "prompt": "Create a project launch plan for Q2 2026",
      "model_profile": "premium",
      "start_date": "2026-04-01T20:55:00+02:00",
      "user_api_key": "your_optional_api_key"
    }
  }
}

Parameter Guide:

• prompt (required): Your planning request in natural language. Write as flowing prose (not structured markdown), typically 300-800 words.
• model_profile (optional): One of "baseline", "premium", "frontier", or "custom". Defaults to "baseline".
• start_date (optional): Plan start date in ISO 8601 format with timezone offset (e.g. "2026-04-01T20:55:00+02:00"). When omitted, the plan starts now.
• user_api_key (optional): Your PlanExe API key (if not set in environment)

Returns: task_id for polling status and retrieving results.

---

Tool 4: plan_status

Poll the status of a running planning task.

Parameters:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "plan_status",
    "arguments": {
      "task_id": "task_abc123def456"
    }
  }
}

Usage: Planning tasks typically take 10-20 minutes (baseline profile). Poll every 5+ minutes to check progress.

Returns: Current status (pending, processing, completed, failed), and progress percentage.

---

Tool 5: plan_stop

Stop a running planning task.

Parameters:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "plan_stop",
    "arguments": {
      "task_id": "task_abc123def456"
    }
  }
}

Returns: Confirmation that the task has been stopped.

---

Tool 6: model_profiles

Return available model profiles and their guidance before calling plan_create.

No required parameters:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "model_profiles",
    "arguments": {}
  }
}

Returns: Available model profiles (baseline, premium, frontier, custom) with descriptions and currently loaded models.

---

Tool 7: plan_file_info

Retrieve download information for completed plan artifacts.

Parameters:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "plan_file_info",
    "arguments": {
      "task_id": "task_abc123def456",
      "artifact": "report"
    }
  }
}

Artifact Options:

• "report": Interactive HTML report (~700KB, self-contained — open in a browser)
• "zip": Pipeline output bundle (md, json, csv intermediary files)

Returns: download_url for accessing the artifact.

---

Tool 8: plan_list

List recent tasks for an authenticated user. Useful for recovering a lost task_id.

Parameters:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "plan_list",
    "arguments": {
      "user_api_key": "pex_your_key_here",
      "limit": 10
    }
  }
}

Returns: List of recent tasks with task_id, state, progress_percentage, created_at, and prompt_excerpt.

---

Tool 9: plan_retry

Retry a failed task with an optional upgraded model profile.

Parameters:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "plan_retry",
    "arguments": {
      "task_id": "task_abc123def456",
      "model_profile": "premium"
    }
  }
}

Returns: Confirmation that the task was requeued to pending state.

---

Typical Workflow

1. Optionally call example_plans to preview what PlanExe output looks like
2. Call example_prompts to understand available planning scenarios
3. Optionally call model_profiles to choose an appropriate model_profile
4. Formulate your planning prompt
5. Get user approval for the request
6. Call plan_create with your prompt and parameters → receives task_id
7. Poll plan_status every 5+ minutes until status is completed or failed
8. If failed, optionally call plan_retry to requeue with a stronger model
9. Call plan_file_info with completed task_id to get download link
10. Download and use the generated plan
11. If you lose a task_id, call plan_list with your user_api_key to recover it

Refer to the PlanExe API documentation for extended examples and advanced use cases.

Configuration Reference

| Variable | Example | Description | |----------|---------|-------------| | PLANEXE_MCP_URL | https://mcp.planexe.org | MCP endpoint URL | | PLANEXE_API_KEY | pk_live_abc123... | API authentication key |

Troubleshooting

Connection Refused

• Verify PLANEXE_MCP_URL is correct
• For Docker: Ensure the container is running (docker ps)
• Check network connectivity between OpenClaw and the service

Authentication Failed

• Verify PLANEXE_API_KEY is valid
• Check for typos or expired credentials
• For cloud: Log in to home.planexe.org to verify account status

Timeout Errors

• For Docker deployments, allow time for container initialization
• Check if the service is overloaded
• Consider increasing the request timeout in your OpenClaw config

Docker Issues (Local/Remote)

• Verify Docker is installed: docker --version
• Check container logs: docker logs <container-id>
• Ensure port 8001 is not in use: lsof -i :8001 (macOS/Linux)

Support

For issues or questions:

• Check the PlanExe documentation
• Visit the PlanExe community forum
• Open an issue on GitHub

License

This skill is part of PlanExe and is available under the same license as the PlanExe project.