Agent Host Protocol – Copilot Skill

You have access to an MCP server (ahp-websocket) that lets you connect to an Agent Host Protocol server over WebSocket and exchange JSON-RPC 2.0 messages.

Available MCP tools

Quick-start workflow

1. connect(url: "ws://localhost:3000")
2. send initialize notification
3. wait for serverHello via get_notifications
4. subscribe to root state
5. create a session, subscribe, send turns

Protocol overview

AHP is a Redux-inspired state synchronisation protocol built on JSON-RPC 2.0 over WebSocket. The server maintains an authoritative state tree; clients apply actions optimistically and reconcile with the server's echoed actions.

Key concepts:

• Root state (ahp-root://) – lists available agents/models.
• Session state (ahp-session:/<uuid>) – per-conversation state with turns, deltas, tool calls, and permissions.
• Actions – the sole mutation mechanism, wrapped in ActionEnvelopes with a serverSeq.
• Subscriptions – clients subscribe to URI-identified state resources to receive action streams.
• Notifications – ephemeral broadcasts (session added/removed) that are NOT part of the state tree and NOT replayed on reconnect.

Connection lifecycle

1. Initialize

Send an initialize notification (no id field):

{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {
    "protocolVersions": ["0.3.0"],
    "clientId": "<unique-client-id>",
    "initialSubscriptions": ["ahp-root://"]
  }
}

Then call get_notifications(wait: 2) to collect the serverHello response, which includes snapshots for any initial subscriptions.

2. Subscribe to state

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscribe",
  "params": { "channel": "ahp-root://" }
}

The response contains the current state snapshot. After subscribing, subsequent mutations arrive as action notifications.

3. Create a session

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "createSession",
  "params": {
    "session": "<provider>:/<uuid>",
    "provider": "<provider>",
    "model": "<model-id>"
  }
}

Then subscribe to the session URI. Wait for a session/ready action.

4. Send a message (start a turn)

Dispatch a session/turnStarted action as a notification (fire-and-forget):

{
  "jsonrpc": "2.0",
  "method": "dispatchAction",
  "params": {
    "channel": "<provider>:/<uuid>",
    "clientSeq": 1,
    "action": {
      "type": "session/turnStarted",
      "turnId": "<unique-turn-id>",
      "userMessage": { "text": "Hello, world!" }
    }
  }
}

Then poll get_notifications(wait: 2) to collect streaming session/delta actions until you see session/turnComplete.

5. Handle tool calls and permissions

If the agent calls a tool, the server sends:

• session/toolStart – tool invocation started
• session/permissionRequest – user approval needed

Resolve permissions with:

{
  "jsonrpc": "2.0",
  "method": "dispatchAction",
  "params": {
    "channel": "<provider>:/<uuid>",
    "clientSeq": 2,
    "action": {
      "type": "session/permissionResolved",
      "turnId": "<turn-id>",
      "requestId": "<perm-request-id>",
      "approved": true
    }
  }
}

6. Other commands

7. Reconnection

If the connection drops, call connect again and send a reconnect message instead of initialize:

{
  "jsonrpc": "2.0",
  "method": "reconnect",
  "params": {
    "clientId": "<same-client-id>",
    "lastSeenServerSeq": 42,
    "subscriptions": ["ahp-root://", "<provider>:/<uuid>"]
  }
}

Action types reference

Client-dispatchable actions

Server-originated actions

Full documentation

For complete protocol details, refer to the docs in this repository:

• Guide: docs/guide/ – conceptual overviews and walkthroughs
  • getting-started.md – end-to-end example
  • state-model.md – full state tree shape
  • actions.md – how actions work
  • reconciliation.md – write-ahead reconciliation algorithm
• Specification: docs/specification/ – normative protocol spec
  • transport.md – transport requirements
  • lifecycle.md – connection, session, and reconnection lifecycle
  • subscriptions.md – subscription mechanics
  • versioning.md – version negotiation
• Reference: docs/reference/ – complete type references
  • messages.md – all state types
  • actions.md – all action types with fields
  • commands.md – all JSON-RPC commands
  • notifications.md – all notification types
  • error-codes.md – error code reference

Read these files when you need exact field names, type shapes, or edge-case behaviour.