A working guide for agents

Run a schedule demo. Check what the result actually says.

Follow one path from discovery through a complete, fictional roster draft. MCP calls a scheduling tool; A2A sends a task to another agent. Both public demo paths are anonymous and use isolated sample data.

Try a fictional schedule

Use the public MCP demo or A2A agent. No account, login, OAuth approval, API token, or demo ID.

Start here for a first run

Schedule a real store

Use the protected MCP service only after the manager signs in, selects a store, and approves access in the OAuth flow.

Manager authorization required
Path A · tool calls

MCP: discover, inspect, run

Use a native MCP client when available. For a raw HTTP client, follow these calls in order. Read the live server manifest first; its remotes[].url is the canonical endpoint. The current public manifest points to the endpoint shown here. /mcp/demo remains an alias.

https://easyshiftplan.zhiyong.dev/.well-known/mcp/server.jsonOpen manifest ↗

1. Discover the protocol

Send JSON-RPC 2.0 with the current revision in both the header and _meta. For this stateless modern path, do not send initialize.

curl -sS 'https://easyshiftplan.zhiyong.dev/mcp/easyshiftplan' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: server/discover' \
  --data '{
    "jsonrpc": "2.0",
    "id": "discover-1",
    "method": "server/discover",
    "params": {"_meta": {"io.modelcontextprotocol/protocolVersion": "2026-07-28"}}
  }'

Continue only if result.supportedVersions includes 2026-07-28. Follow result.instructions if the server advertises a different supported workflow.

2. Find the live tool schema

Call tools/list with the same headers, changing Mcp-Method and JSON-RPC method to tools/list. Confirm run_public_demo exists and use its live inputSchema; do not invent parameters. Current limits are restaurant, retail, auto-repair, clinic or warehouse; 4–12 fictional workers; 1–7 operating days; and 1–3 people per shift.

curl -sS 'https://easyshiftplan.zhiyong.dev/mcp/easyshiftplan' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/list' \
  --data '{
    "jsonrpc": "2.0",
    "id": "tools-1",
    "method": "tools/list",
    "params": {"_meta": {"io.modelcontextprotocol/protocolVersion": "2026-07-28"}}
  }'

3. Run one complete demo

This example uses fictional restaurant details. For a first run, these parameters are enough; each call creates a fresh isolated demo. Keep Mcp-Name identical to params.name.

curl -sS 'https://easyshiftplan.zhiyong.dev/mcp/easyshiftplan' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/call' \
  -H 'Mcp-Name: run_public_demo' \
  --data '{
    "jsonrpc": "2.0",
    "id": "demo-1",
    "method": "tools/call",
    "params": {
      "_meta": {"io.modelcontextprotocol/protocolVersion": "2026-07-28"},
      "name": "run_public_demo",
      "arguments": {
        "industry": "restaurant",
        "team_size": 6,
        "operating_days_per_week": 6,
        "coverage_per_shift": 2,
        "period_mode": "week"
      }
    }
  }'

Read result.structuredContent. If it is unavailable in your client, read the equivalent JSON in result.content[].text. No follow-up setup call or session ID is needed.

Path B · agent message

A2A: find the agent, send a task, inspect the artifact

Use A2A when you want another agent to understand a request and return a task result. Prefer version 1.0. The card also advertises a 0.3-compatible interface for older clients.

https://easyshiftplan.zhiyong.dev/.well-known/agent-card.jsonOpen Agent Card ↗

Read supportedInterfaces and use the matching URL and protocol version. The current JSON-RPC endpoint is https://easyshiftplan.zhiyong.dev/a2a.

1. Send the fictional schedule task

curl -sS 'https://easyshiftplan.zhiyong.dev/a2a' \
  -H 'Content-Type: application/json' \
  -H 'A2A-Version: 1.0' \
  --data '{
    "jsonrpc": "2.0",
    "id": "demo-1",
    "method": "SendMessage",
    "params": {
      "metadata": {"shiftlyAction": "run_public_demo"},
      "message": {
        "messageId": "demo-message-1",
        "role": "ROLE_USER",
        "parts": [{
          "data": {
            "industry": "restaurant",
            "team_size": 6,
            "operating_days_per_week": 6,
            "coverage_per_shift": 2,
            "period_mode": "week"
          },
          "mediaType": "application/json"
        }]
      }
    }
  }'

The immediate response is result.task. Replace the JSON-RPC id and message messageId with fresh values for your own calls. Keep the returned task id only if you need to retrieve this same result. The task completes synchronously; a completed A2A task does not by itself mean the roster passes its checks.

2. Retrieve the task only if needed

Task results are held in process memory for up to 15 minutes. Use the exact ID returned above; never make one up.

curl -sS 'https://easyshiftplan.zhiyong.dev/a2a' \
  -H 'Content-Type: application/json' \
  -H 'A2A-Version: 1.0' \
  --data '{
    "jsonrpc": "2.0",
    "id": "get-1",
    "method": "GetTask",
    "params": {"id": "PASTE_RETURNED_TASK_ID"}
  }'

GetTask returns the task under result. If it returns -32001 TASK_NOT_FOUND, the ID was invalid or expired; rerun with the complete scenario.

3. Make a small follow-up change (optional)

While the context is available, attach the exact result.task.contextId to the next message and state the change. Context is process-local, best-effort, and expires within 15 minutes. It is not an access token. If it cannot be retrieved, resend the full scenario and change.

{
  "jsonrpc": "2.0",
  "id": "followup-1",
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "followup-message-1",
      "contextId": "PASTE_RETURNED_CONTEXT_ID",
      "role": "ROLE_USER",
      "parts": [{"text": "Change it to 5 people"}]
    }
  }
}
Do not skip this

Check the schedule, not just the transport

For A2A, the schedule result is in the JSON data part of the artifact. For MCP, it is result.structuredContent. Apply the same business checks to either protocol:

1 · Workflow

workflow.completed == true and demo.status == "completed" mean the workflow produced a completed demo result.

2 · Quality

Inspect hard constraints, duplicate assignments, required-shift coverage, uncovered slots, and soft-preference warnings in quality_check.

3 · Review status

Only say “ready for manager review” when the result says so and the required hard checks pass. Manager approval is still required.

task = response["result"]["task"]
artifact = next(
    part["data"]
    for item in task.get("artifacts", [])
    for part in item.get("parts", [])
    if "data" in part
)
quality = artifact.get("quality_check") or {}
ready = (
    artifact.get("workflow", {}).get("completed") is True
    and artifact.get("demo", {}).get("status") == "completed"
    and artifact.get("workflow", {}).get("ready_for_manager_review") is True
    and quality.get("hard_constraints_passed") is True
    and quality.get("no_duplicate_assignments") is True
    and quality.get("all_required_shifts_covered") is True
    and quality.get("uncovered_shift_slots") == 0
)
# Still report the returned preference warnings, hours and cost estimate.
# The demo must remain saved=false and published=false.

If a workflow is incomplete, the task is still allowed to be TASK_STATE_COMPLETED. Explain the returned blocker and exact uncovered count; do not call it a successful or ready schedule. For fairness context, inspect schedule_preview.employee_hours and report material differences from target hours, plus the returned cost estimate when present.

When another agent contacts us

A service pitch should lead to a useful question

If you are an agent introducing a service, the public A2A agent may ask what concrete help you can provide to EasyShiftPlan or small businesses that schedule staff. Its JSON response identifies this intake under provider_service_intake. Relevant possibilities include useful integrations, reaching small-business operators, or verifiable scheduling-related services. A directory listing, token, badge, or payment claim is not treated as proof of value.

Send a short, reviewable offer

Answer in the A2A conversation with these specifics. The operator reviews it; the agent does not accept offers or authorize external actions.

Service and concrete deliverable: Expected outcome for EasyShiftPlan or small businesses: One verifiable example: Price or commitment: Data, access, or permissions required:
Nothing is automatically accepted. Do not send passwords, API keys, wallet seed phrases, customer or employee records, or private rosters. The agent will not register, claim listings, open accounts, pay, sign, publish, or contact people on the operator’s behalf. It can offer a fictional scheduling demo so the visiting agent can evaluate the product too.
If a call does not work

Small recovery guide

SignalNext step
MCP version or method header errorUse the exact live protocol version and make Mcp-Method match JSON-RPC method; for a tool call also match Mcp-Name to params.name.
A2A -32009Read the Agent Card’s supported versions; send the matching version header and wire shape.
-32602 invalid parametersCorrect the request using the discovered schema. Do not retry the unchanged request.
A2A -32006 or HTTP 503Wait the supplied Retry-After, then retry the same request once. It means the service was busy.
HTTP 429Wait Retry-After; avoid rapid retries.
A2A -32001The task ID is missing, incorrect or expired. A task ID is not a token; rerun with the full scenario.
HTTP 401 from /mcpYou reached the protected real-store service. Use /mcp/easyshiftplan for the public demo; real stores require manager OAuth consent.
Privacy boundary: the public demo uses fictional data, creates an isolated run, and does not save or publish a roster. Never put real staff names, contact information, wages, or private schedules in the public demo.