MCP server

Every verified site gets its own MCP server (Model Context Protocol) at Sill’s edge. An AI agent or MCP client connects to it, lists your store’s skills as MCP tools and calls them. You do not run or host anything; Sill serves it for you.

Find your MCP endpoint

POST https://edge.sill.so/v1/mcp/{site_key}

Copy the exact URL from Settings → Install → Endpoint → MCP endpoint. The same URL is listed in your signed agent card (mcp_endpoint), your ARD catalog, your llms.txt and your /agent page, so agents that find any of those find the server too.

MCP endpoint row in Settings showing the store's edge.sill.so MCP URL with a copy button Paste this URL into any MCP client that supports Streamable HTTP.

A Cloudflare Worker or WordPress plugin install also serves /.well-known/mcp/server-card.json on your own domain, a small JSON file that points to this endpoint.

Supported methods

The server speaks MCP over Streamable HTTP and answers each request with a single JSON response. It supports three methods:

Method	What it does
`initialize`	Handshake. Returns protocol version `2025-06-18` and a tools-only capability set.
`tools/list`	Returns your store’s live skills as MCP tools.
`tools/call`	Calls one skill. Every call is recorded in your signed audit log.

Any other method returns JSON-RPC error -32601 (method not found).

Example: initialize

POST /v1/mcp/SITE_KEY HTTP/1.1
Host: edge.sill.so
Content-Type: application/json
Accept: application/json, text/event-stream

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": { "name": "example-client", "version": "1.0.0" }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": { "tools": { "listChanged": false } },
    "serverInfo": { "name": "sill", "version": "2025-06-18" }
  }
}

The server keeps no session, so you can call tools/list or tools/call without calling initialize first.

Example: tools/list

{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }

Response (shortened to one tool):

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "browse_catalog",
        "description": "Search and browse the product catalog",
        "inputSchema": {
          "type": "object",
          "properties": {
            "query": { "type": "string", "minLength": 1, "maxLength": 256 },
            "category": { "type": "string", "minLength": 1, "maxLength": 128 },
            "limit": { "type": "integer", "minimum": 1, "maximum": 50 },
            "cursor": { "type": "string", "minLength": 1, "maxLength": 512 }
          },
          "additionalProperties": false
        }
      }
    ],
    "nextCursor": null
  }
}

Each tool’s name is the skill’s skill_id. The list contains the skills that are live for your store: enabled in Settings → Skills and backed by something that can answer them (see Skills). It is the same set your signed agent card, catalog and /agent page list: place_order and request_refund appear only after the store connects a store platform or payment provider, and a store with no live skills returns an empty list. The seven default skills carry a full input schema; custom skills accept any JSON object.

Ask for only some tools

To get a shorter list, name the skills you want in params._meta.sill_scope:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/list",
  "params": { "_meta": { "sill_scope": ["browse_catalog", "check_availability"] } }
}

The response contains only the listed skills that the store offers. Names the store does not offer, and entries that are not valid skill ids (a lowercase letter followed by lowercase letters, digits or underscores, up to 64 characters), are ignored; only the first 32 valid entries count. An empty sill_scope, or one where no entry is valid, returns every tool. To get no tools, don’t call tools/list.

sill_scope only shortens the list. It does not limit what tools/call will accept; the store’s guardrails decide that.

Calling a skill

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": { "name": "browse_catalog", "arguments": { "query": "decaf", "limit": 5 } }
}

What the agent gets back depends on how the skill is backed:

Backed by a connected store, the store’s catalog in Sill, or the merchant’s own endpoint: the real answer, in structuredContent. Arguments are checked against the tool’s inputSchema first.
place_order and request_refund: need a signed mandate in arguments.mandate, evaluated against the store’s guardrails. See Signed mandates.
Listed but with nothing to answer it (for example an Advertised custom skill): a success result with structuredContent.sill_mode set to "discovery" and the text This store has not enabled this action yet. The call has been recorded in the store’s audit log. Nothing was executed.

Errors and limits

Situation	HTTP status	Body
Unknown, malformed or revoked site key	`404`	JSON-RPC error, message `site not found`
Request body over 64 KB	`413`	—
Body is not valid JSON-RPC 2.0	`400`	JSON-RPC error `-32700` or `-32600`
Method other than `POST` (or `OPTIONS`)	`405`	—
Temporarily unavailable	`503`	JSON-RPC error; retry later
Unknown tool name, a skill the store has not turned on, missing `params` or invalid arguments	`200`	JSON-RPC error `-32602` (message `unknown_tool` for a name the store does not offer)
`place_order` or `request_refund` on a store that has not connected a store platform or payment provider	`404`	JSON-RPC error, message `site not found`
Too many requests	`200`	JSON-RPC error `-32603`, message `rate_limited`, `data.retry_after_seconds: 60`

initialize and tools/list are rate-limited per site and per client IP address, so an agent that loops on tools/list is slowed down without affecting other agents. tools/call has its own per-site limits. MCP responses are not signed; the signed documents that point to this server are the agent card and the catalog.