Connect your AI assistant

HoneyDew includes a built-in MCP server for agents. It starts with the backend on every normal installation; no separate MCP process or plugin is required. REST and the Python helpers remain available.

Quick start: built-in MCP

1. Install/update dependencies with ./install.sh, then start HoneyDew with ./start.sh.
2. Open Settings → Connect agents for the endpoint, copyable configuration, and a read-only connection test.
3. Add the endpoint to your agent's MCP settings using Streamable HTTP. The direct backend endpoint is http://localhost:8000/mcp/. The standard development frontend also proxies /mcp/, so the URL shown in Settings works through that frontend.
4. Reload/enable the connection in your client. Ask it to call get_config, list_boards, and get_board for your intended board. Discover actual profile and column IDs; never assume the examples match your installation.

For clients using an mcpServers configuration (including Cursor), merge this entry with existing servers:

{
  "mcpServers": {
    "honeydew": {
      "url": "http://localhost:8000/mcp/"
    }
  }
}

This JSON is not universal: clients with a connection form should choose Streamable HTTP and enter the URL; clients with a different configuration format should use their supported format. See Cursor MCP and the official MCP Python SDK.

The Settings test performs initialization and tool discovery only. It does not create or claim tasks. Browser reachability does not prove connectivity from a remote agent. Localhost means the machine running the client.

Tools and workflow

• Discover profiles/configuration, list boards, and read columns/card counts.
• Search paginated task/Epic summaries by number, title, or description; fetch full details separately.
• Create/update/delete tasks or Epics, link children, move cards, transfer profiles, and post comments.
• Manage prerequisite links, labels, and session-bound worker leases.
• Inspect attachment/object metadata and checksums; link, rename, or remove existing attachments.
• Read resources at honeydew://config, honeydew://boards, honeydew://cards/{card_id}, and the attachment metadata template; request the task_workflow prompt.

Creates/comments require an explicit author profile. update_card uses a changes object: omitted fields are preserved; explicit null clears nullable fields. list_cards requires a board ID and returns bounded summaries; use get_card for description/comments/subtasks. Search #123 for an exact ticket number.

For authorized implementation: find/reuse a card, acquire its lease with your worker-session identity, move it to In Progress, and add a start comment. Respect conflicts and prerequisites; renew before expiry. Record actual outcomes and verification, move to Done, and release the lease if still held. Epics organize tasks but cannot be leased. Never fabricate usage data. MCP uses the same REST validation and conflicts; it does not introduce a new authorization model.

File transfers: HTTP MCP does not accept host filesystem paths, expose storage credentials, or change storage configuration. Upload/download bytes through existing REST endpoints or use local stdio below. Metadata content_url values are relative to the API origin, not the MCP endpoint path.

OpenClaw

Add a Streamable HTTP server through your OpenClaw version's supported MCP settings, using the reachable /mcp/ endpoint. Preserve unrelated servers and customized HoneyDew skills. A new session/runtime may be needed to discover tools. The bundled skills/honeydew/SKILL.md remains useful workflow context and a REST fallback; it is not required for the endpoint. See OpenClaw skills CLI.

Copy-paste setup prompt for OpenClaw

Connect this OpenClaw agent to my existing HoneyDew installation.

Inspect existing MCP connections and preserve unrelated configuration and customized HoneyDew instructions. Use http://localhost:8000/mcp/ as the initial Streamable HTTP endpoint only if reachable from this agent's tool runtime. For a remote/container agent, use my private reachable HoneyDew URL. Do not expose the service publicly or request credentials in chat.

Register HoneyDew through this OpenClaw version's supported MCP settings. If MCP is unavailable, inspect the checkout's skills/honeydew/SKILL.md and use the existing REST API as a fallback. Do not invent configuration keys or CLI flags. Tell me if a new session is needed.

Verify initialization, tool discovery, get_config, list_boards and get_board. Discover actual board/profile/column IDs. Do not create, move, delete or claim cards merely to test setup. For future authorized work, respect the task_workflow prompt, worker leases and prerequisites; record actual outcomes and verification before Done. Never fabricate usage or start background work during setup.

Report the verified endpoint, board/profile IDs and remaining network/client limitations. Finish with a read-only board summary.

Cursor

Merge the Quick Start entry into the project's .cursor/mcp.json or global Cursor MCP settings; preserve other entries. Enable it and verify read-only discovery. Project rules can describe when to use HoneyDew, but are not required to expose tools. See Cursor MCP and Cursor Rules.

Copy-paste setup prompt for Cursor

Set up this Cursor project to use my existing HoneyDew task board.

Inspect existing project/global MCP settings and preserve other servers and rules. Add a HoneyDew Streamable HTTP connection using http://localhost:8000/mcp/ if reachable from the agent runtime, or my private reachable endpoint when running remotely. Use Cursor's supported MCP configuration; do not overwrite the configuration file or expose HoneyDew publicly.

Verify initialization, tool discovery, get_config, list_boards and get_board. Discover the actual board, column and author profile IDs. Do not create, move, delete or claim tasks to test setup. If persistent project instructions are wanted, merge a focused HoneyDew rule without altering unrelated rules.

For future authorized implementation, find/reuse a task, acquire a session-bound lease, respect conflicts/prerequisites, comment on progress, and record actual verification before Done. Do not fabricate token usage or begin autonomous work during setup. Report the verified endpoint and read-only board summary, noting client/network limitations.

Optional local stdio and file transfers

The original stdio entry point remains supported and now includes task tools as well as file transfers. Backend installation includes its MCP dependency. A stdio-only client may launch:

{
  "mcpServers": {
    "honeydew": {
      "command": "/absolute/path/to/honeydew/.venv/bin/python",
      "args": ["-m", "tools.mcp_server"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/honeydew",
        "SMARTIFY_API_URL": "http://localhost:8000",
        "HONEYDEW_MCP_READ_ROOTS": "/absolute/path/to/approved/exports",
        "HONEYDEW_MCP_WRITE_ROOTS": "/absolute/path/to/approved/downloads"
      }
    }
  }
}

Use the actual Python environment created by your installer. File paths belong to the stdio process's host; read/write roots are explicit and narrow. Without roots, file transfers are disabled; metadata/task tools still work. Downloads verify checksums and refuse overwrites. Existing stdio configurations remain valid. See Attachments.

Private network deployments

The endpoint uses the existing unauthenticated, trusted-local/private-network model. Profile IDs and lease IDs are not login credentials. Do not publish it directly to the Internet. Remote use needs a private tunnel/VPN or an authenticated reverse proxy protecting both REST and MCP.

start.sh binds the backend to 127.0.0.1 by default. For deliberate private-network/container deployment, set HONEYDEW_HOST to the required bind address. The SDK validates Host and Origin headers:

• Loopback hosts and HTTP loopback origins are allowed by default.
• HONEYDEW_MCP_ALLOWED_HOSTS: comma-separated trusted hostname[:port] values matching incoming Host. A hostname with :* allows its ports.
• HONEYDEW_MCP_ALLOWED_ORIGINS: comma-separated trusted browser origins including scheme/port. Native clients usually send no Origin. Bare * is rejected.
• Restart the backend after changing these values. They are allowlists, not authentication.

A private reverse proxy preserving its host header could use:

HONEYDEW_MCP_ALLOWED_HOSTS=tasks.internal.example
HONEYDEW_MCP_ALLOWED_ORIGINS=https://tasks.internal.example

Forward /mcp/ and its POST/protocol headers to the backend. A custom frontend must proxy /api and /mcp, or set VITE_API_BASE_URL to its reachable API origin. Cross-origin browser use additionally needs an appropriate REST/CORS policy. Cloud agents unable to reach your private network cannot connect to localhost merely by installing a plugin.

REST fallback and troubleshooting

See the API reference for the full REST contract.

GET /health, GET /api/mcp, GET /api/config, and GET /api/boards are read-only checks. REST docs remain at /docs and /openapi.json. Python helpers use SMARTIFY_API_URL; embedded MCP calls its own application directly and needs no loopback URL setting.

Problem	Resolution
Connection refused	Start HoneyDew; verify host, port and reachability from the agent runtime.
/mcp/ is missing	Update the checkout, install dependencies, and restart the backend.
Plain browser GET returns 405/406	Normal for this JSON-response endpoint. Use MCP initialization or Settings → Test MCP connection.
HTTP 421 / 403	Check Host / Origin allowlists respectively; do not disable protections globally.
Browser works but agent fails	Verify from the agent runtime and check its tool permissions.
Invalid profile / validation error	Call get_config; creates/comments need an explicit profile.
Claim returns 409	Inspect the current lease and prerequisites; do not force a takeover.
File-path tool absent over HTTP	Use REST byte transfer or local stdio.
Stdio module not found	Use the correct Python environment and absolute checkout PYTHONPATH.