Conversations and polling

ask_holyshift starts a project agent run and immediately returns a conversation_id, a working status and a HolyShift conversation URL. The run uses the same project capabilities and credit meter as HolyShift's own assistant.

Ask once, then poll

Call get_answer with the same project_id and conversation_id about every 30 seconds. An answer typically takes one to several minutes. Do not resubmit the question just because the first poll says working.

Status	What your client should do
working	Wait and poll again.
answered	Show answer and stop polling.
waiting_for_you	Show the conversation url and explain that the person must respond in HolyShift. Pause background polling until they return, then check again.
failed	Show reason and stop polling. Offer an explicit retry.

The waiting_for_you result can include partial answer text and a waiting_for list. Partial text is not a completed response.

Example client loop

This example uses an already authenticated and initialized MCP SDK session. Dictionary tool results are available in structuredContent.

import asyncio

async def ask_and_wait(session, project_id, question):
    started = await session.call_tool("ask_holyshift", {
        "project_id": project_id,
        "question": question,
    })
    if started.isError or started.structuredContent is None:
        return started

    conversation = started.structuredContent
    # A bounded polling window avoids a client waiting forever. Keep the
    # conversation ID so the user can check again without submitting twice.
    for _ in range(20):
        await asyncio.sleep(30)
        result = await session.call_tool("get_answer", {
            "project_id": project_id,
            "conversation_id": conversation["conversation_id"],
        })
        if result.isError or result.structuredContent is None:
            return result
        conversation = result.structuredContent
        if conversation["status"] != "working":
            return conversation
    return conversation

Handle authentication refresh and HTTP failures in the session's transport layer. If the connection drops after ask_holyshift, do not blindly replay the mutating call: first recover the result or check the conversation in HolyShift.

Follow up

Pass the earlier conversation_id to ask_holyshift to continue with its context. Leave it out to create a new conversation.

A conversation accepts no second question while its run is queued, running or waiting for the person. A follow-up must be in the same project and the caller's own conversation.

User decisions stay in HolyShift

MCP cannot approve a parked call or answer a pending user question. Direct the person to the returned URL. Once they respond in HolyShift, the work can continue; your client checks the same conversation again.

Revoking the app's access stops future calls; it does not cancel a run already submitted.