Build a provider

A provider is an MCP server inside your app, one file on disk and two resources. This outline shows the order of work and the JSON on the wire. It does not depend on any SDK. The specification has every field.

The examples use a made-up editor, org.example.editor, with two Markdown files open and a sentence selected in one.

What you need

Your app already has most of what a provider reports. It has its windows, its open documents and its selection in memory. It knows where things are drawn in the code that draws and hit-tests its content. The work is exposing that.

A provider has four jobs: listen, write the descriptor, answer current and answer locate. The last is optional.

Steps

{
  "resultType": "complete",
  "supportedVersions": ["2026-07-28"],
  "capabilities": {
    "resources": {},
    "extensions": {
      "io.github.ambientcontextprotocol/context": { "version": "0.2.0" }
    }
  },
  "_meta": {
    "io.modelcontextprotocol/serverInfo": { "name": "Editor", "version": "2.3.0" }
  }
}

{
  "resultType": "complete",
  "resources": [
    {
      "uri": "ambient://current",
      "name": "current",
      "title": "Current context",
      "description": "What the user has open and selected in this app, right now.",
      "mimeType": "application/json"
    }
  ]
}

{
  "resultType": "complete",
  "resourceTemplates": [
    {
      "uriTemplate": "ambient://location/{id}",
      "name": "location",
      "title": "Location of an element",
      "description": "Where an element from the current context is on screen.",
      "mimeType": "application/json"
    }
  ]
}

{
  "protocol": "0.2.0",
  "app": { "id": "org.example.editor", "name": "Editor", "version": "2.3.0" },
  "pid": 48211,
  "instance": "k3f9x2",
  "endpoint": "http://127.0.0.1:53124/mcp",
  "token": "q7Jm…",
  "started": "2026-11-09T21:14:03Z"
}

Answer current

The host asks what is open and what the user is pointing at. The request is a standard MCP resources/read; the headers and _meta fields come from the MCP 2026-07-28 HTTP transport.

POST /mcp HTTP/1.1
Host: 127.0.0.1:53124
Authorization: Bearer q7Jm…
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2026-07-28
Mcp-Method: resources/read
Mcp-Name: ambient://current

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "resources/read",
  "params": {
    "uri": "ambient://current",
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

curl -s http://127.0.0.1:53124/mcp \
  -H 'Authorization: Bearer q7Jm…' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: resources/read' \
  -H 'Mcp-Name: ambient://current' \
  -d '{"jsonrpc":"2.0","id":7,"method":"resources/read","params":{"uri":"ambient://current","_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'

The result's contents array holds exactly one entry: the uri that was read, mimeType application/json, and text holding the answer as a JSON document.

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "resultType": "complete",
    "contents": [
      {
        "uri": "ambient://current",
        "mimeType": "application/json",
        "text": "{ \"protocol\": …, \"instance\": …, \"root\": … }"
      }
    ]
  }
}

Decoded, the text is one tree of elements rooted at the app:

{
  "protocol": "0.2.0",
  "instance": "k3f9x2",
  "root": {
    "id": "app", "role": "Application", "title": "Editor",
    "children": [
      { "id": "win-1", "role": "Window", "focused": true, "children": [
        { "id": "doc-1", "role": "Document", "subrole": "markdown", "title": "draft.md",
          "url": "file:///Users/ada/essays/draft.md", "focused": true, "children": [
            { "id": "sel-23", "role": "Text", "selected": true,
              "content": [
                { "type": "text", "text": "The command line lasted thirty years as the main way people used computers." }
              ],
              "attributes": { "lines": [31, 31] } }
        ] },
        { "id": "doc-2", "role": "Document", "subrole": "markdown", "title": "notes.md",
          "url": "file:///Users/ada/essays/notes.md", "visible": false }
      ] }
    ]
  }
}

Build the tree of what is open, mint an id for each element, and mark what is selected, focused and, if your app tracks the pointer, hovered. protocol and instance are the same values as in the descriptor. Concepts explains roles and states, and the answer's shape is also published as a JSON Schema, schema/current-0.2.0.json in the repository.

Answer from state you already hold in memory, without waiting on disk or network. A host sets its own time limit and carries on without context if you miss it.

Answer locate

The host asks where an element is by reading ambient://location/{id} with the element's id in place of {id}. Only the address in the body and in the Mcp-Name header changes.

POST /mcp HTTP/1.1
Host: 127.0.0.1:53124
Authorization: Bearer q7Jm…
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2026-07-28
Mcp-Method: resources/read
Mcp-Name: ambient://location/sel-23

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "resources/read",
  "params": {
    "uri": "ambient://location/sel-23",
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

curl -s http://127.0.0.1:53124/mcp \
  -H 'Authorization: Bearer q7Jm…' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: resources/read' \
  -H 'Mcp-Name: ambient://location/sel-23' \
  -d '{"jsonrpc":"2.0","id":8,"method":"resources/read","params":{"uri":"ambient://location/sel-23","_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'

The response has the same shape as before, with the location as its text:

{
  "id": "sel-23",
  "state": "visible",
  "rects": [{ "x": 425, "y": 233, "w": 480, "h": 20 }],
  "window": 9120,
  "avoid": { "x": 400, "y": 80, "w": 620, "h": 900 },
  "edge": "right"
}

Rectangles are in global display coordinates, in points, with the origin at the top-left corner of the primary display and y increasing downward. AppKit's own coordinates have a bottom-left origin and must be converted.

An id you issued whose element no longer exists is not an error: answer with state: "gone". An id you never issued in this run, or an element you cannot place, is JSON-RPC error -32602.

Errors and refusals

A request with no MCP version in its body, and either no MCP-Protocol-Version header or one naming an older revision, comes from an older client. Treat it as one and do not refuse it. Supporting older clients is more than one extra method: requests, results and errors differ between the revisions. The binding reference has the details.

An optional tool

An agent connected straight to a provider, with no host between them, cannot read a resource on its own initiative in every MCP client. A provider may therefore also offer one tool, context_current, which takes no arguments and returns the current result as structured content, with the same JSON as a text block. A host never uses it, and a provider is complete without it.