Chapter 14: The Model Context Protocol (MCP)

TL;DR

• MCP is the JSON-RPC-like protocol for all backend communication in Worka.
• Your backend must run an HTTP server that accepts POST requests.
• The most important request method is tool.call.
• Example Request from Host:

  {
    "jsonrpc": "2.0",
    "method": "tool.call",
    "params": {
      "name": "your_tool_name",
      "arguments": { "param1": "value1" }
    }
  }

• Example Response from Server:

  {
    "jsonrpc": "2.0",
    "result": { "some_data": "your_response" }
  }

• Your server can also send elicit requests back to the host to get user input or to securely call other tools.

---

For the Worka Host to be able to communicate with backend servers written in any language (Rust, Node.js, Python, Go, etc.), they must all speak a common language. This standard language is the Model Context Protocol (MCP).

Understanding the basics of MCP is helpful, but remember that in practice, you will use a library like the rmcp crate for Rust that handles the low-level protocol details for you.

The Core Flow: tool.call

The primary job of an MCP server is to expose Tools and respond to requests from the Host to execute them. This is done via the tool.call method.

When a pack's UI or an AI Agent wants to run one of your tools, the Worka Host sends your MCP server an HTTP POST request. The body of that request is a JSON object that looks like this:

Request: POST /

{
  "jsonrpc": "2.0",
  "method": "tool.call",
  "params": {
    "name": "greet",
    "arguments": {
      "name": "Alice"
    }
  }
}

Your server must parse this request, find the function corresponding to the tool name (greet in this case), execute it with the provided arguments, and then send back a JSON response.

Successful Response:

{
  "jsonrpc": "2.0",
  "result": {
    "greeting": "Hello, Alice!"
  }
}

Error Response:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Invalid params: Missing 'name' argument"
  }
}

Advanced Communication: elicit

Communication is not just one-way. A powerful feature of MCP is that your server can pause its work and send a request back to the Host. This is called an elicitation.

This is an advanced topic that we will cover in detail in later chapters, but there are two main reasons your backend would send an elicit request:

1. To get input from the user: Your tool can ask the Host to render a form and wait for the user to fill it out.
2. To call another tool: Your tool can securely ask the Host to call a tool on another pack, including the virtual packs like worka/db.

This elicit mechanism is the foundation for building complex, interactive, and interconnected workflows on the Worka platform.