PaperpinPaperpin Docs
MCP

MCP tools

Explore every Paperpin MCP tool, including group, monitor, change event, and insights inputs and response shapes.

Resource identifiers use UUID strings. Every tool requires paperpin:read unless a stronger scope is shown. PaperPin enforces scopes before a tool runs and again inside the handler.

MCP response envelope

Every successful tools/call returns one text content item. The text value is a JSON string containing the decoded response documented for each tool below.

{
  "content": [
    {
      "type": "text",
      "text": "{\"deleted\":true}"
    }
  ]
}

The following examples show the decoded JSON inside text.

Groups

list_groups

Inputs: none

[
  {
    "id": "0e838345-648b-46f5-8586-6e8b2f7bbf76",
    "name": "Production",
    "created_at": "2026-07-16T08:00:00.000Z",
    "updated_at": "2026-07-16T08:00:00.000Z"
  }
]

An account with no groups receives [].

get_group

Input: group_id

{
  "id": "0e838345-648b-46f5-8586-6e8b2f7bbf76",
  "name": "Production",
  "created_at": "2026-07-16T08:00:00.000Z",
  "updated_at": "2026-07-16T08:00:00.000Z"
}

A missing group or a group from another tenant returns null.

create_group

Input: name from 1 to 32 characters. Requires paperpin:groups:write.

{
  "conflict": false,
  "group": {
    "id": "0e838345-648b-46f5-8586-6e8b2f7bbf76",
    "name": "Production",
    "created_at": "2026-07-16T08:00:00.000Z",
    "updated_at": "2026-07-16T08:00:00.000Z"
  }
}

If the tenant already has that group name:

{
  "conflict": true,
  "group": null
}

rename_group

Inputs: group_id, name. Requires paperpin:groups:write.

{
  "conflict": false,
  "group": {
    "id": "0e838345-648b-46f5-8586-6e8b2f7bbf76",
    "name": "Marketing",
    "created_at": "2026-07-16T08:00:00.000Z",
    "updated_at": "2026-07-16T09:00:00.000Z"
  }
}

group is null when the group is missing. A duplicate name returns {"conflict":true,"group":null}.

delete_group

Input: group_id. Requires paperpin:delete.

{
  "deleted": true
}

A missing group returns {"deleted":false}.

list_group_monitors

Input: group_id

[
  {
    "id": "99b61a96-40d9-44a6-9fd5-e56e5d29e49f",
    "name": "Pricing page",
    "url": "https://example.com/pricing",
    "group_id": "0e838345-648b-46f5-8586-6e8b2f7bbf76",
    "status": "active",
    "interval_minutes": 60,
    "detection_mode": "visual",
    "sensitivity": "medium",
    "last_successful_check_at": "2026-07-16T08:15:00.000Z",
    "last_detected_change_at": null,
    "created_at": "2026-07-15T08:00:00.000Z",
    "updated_at": "2026-07-16T08:15:00.000Z"
  }
]

An empty group returns []; a missing group returns null.

add_monitor_to_group

Inputs: group_id, monitor_id. Requires paperpin:groups:write.

{
  "group": {
    "id": "0e838345-648b-46f5-8586-6e8b2f7bbf76",
    "name": "Production",
    "created_at": "2026-07-16T08:00:00.000Z",
    "updated_at": "2026-07-16T08:00:00.000Z"
  },
  "missing_monitor_ids": [],
  "monitors": [
    {
      "id": "99b61a96-40d9-44a6-9fd5-e56e5d29e49f",
      "name": "Pricing page",
      "url": "https://example.com/pricing",
      "group_id": "0e838345-648b-46f5-8586-6e8b2f7bbf76",
      "status": "active",
      "interval_minutes": 60,
      "detection_mode": "visual",
      "sensitivity": "medium",
      "last_successful_check_at": "2026-07-16T08:15:00.000Z",
      "last_detected_change_at": null,
      "created_at": "2026-07-15T08:00:00.000Z",
      "updated_at": "2026-07-16T09:00:00.000Z"
    }
  ]
}

A missing group returns {"group":null,"missing_monitor_ids":[],"monitors":null}. A missing monitor returns the group, monitors:null, and the missing ID in missing_monitor_ids.

add_monitors_to_group

Inputs: group_id, monitor_ids with 1 to 100 UUIDs. Requires paperpin:groups:write.

The response shape matches add_monitor_to_group. Duplicate monitor IDs are assigned once. If any monitor is missing or belongs to another tenant, no assignment is attempted and missing_monitor_ids lists the missing IDs.

remove_monitor_from_group

Inputs: group_id, monitor_id. Requires paperpin:groups:write.

{
  "group": {
    "id": "0e838345-648b-46f5-8586-6e8b2f7bbf76",
    "name": "Production",
    "created_at": "2026-07-16T08:00:00.000Z",
    "updated_at": "2026-07-16T08:00:00.000Z"
  },
  "missing_monitor_ids": [],
  "monitors": [
    {
      "id": "99b61a96-40d9-44a6-9fd5-e56e5d29e49f",
      "name": "Pricing page",
      "url": "https://example.com/pricing",
      "group_id": null,
      "status": "active",
      "interval_minutes": 60,
      "detection_mode": "visual",
      "sensitivity": "medium",
      "last_successful_check_at": "2026-07-16T08:15:00.000Z",
      "last_detected_change_at": null,
      "created_at": "2026-07-15T08:00:00.000Z",
      "updated_at": "2026-07-16T09:00:00.000Z"
    }
  ]
}

A missing group returns {"group":null,"missing_monitor_ids":[],"monitors":null}. A monitor that is missing, belongs to another tenant, or is not currently in the group returns the group, monitors:null, and the monitor ID in missing_monitor_ids.

remove_monitors_from_group

Inputs: group_id, monitor_ids with 1 to 100 UUIDs. Requires paperpin:groups:write.

The response shape matches remove_monitor_from_group. Duplicate monitor IDs are removed once. If any monitor is missing, belongs to another tenant, or is not currently in the group, no removal is attempted and missing_monitor_ids lists the missing IDs.

Monitors

list_monitors

Inputs: none

[
  {
    "id": "99b61a96-40d9-44a6-9fd5-e56e5d29e49f",
    "name": "Pricing page",
    "url": "https://example.com/pricing",
    "group_id": "0e838345-648b-46f5-8586-6e8b2f7bbf76",
    "status": "active",
    "interval_minutes": 60,
    "detection_mode": "visual",
    "sensitivity": "medium",
    "last_successful_check_at": "2026-07-16T08:15:00.000Z",
    "last_detected_change_at": null,
    "created_at": "2026-07-15T08:00:00.000Z",
    "updated_at": "2026-07-16T08:15:00.000Z"
  }
]

An account with no monitors receives [].

get_monitor

Input: monitor_id

{
  "id": "99b61a96-40d9-44a6-9fd5-e56e5d29e49f",
  "name": "Pricing page",
  "url": "https://example.com/pricing",
  "group_id": "0e838345-648b-46f5-8586-6e8b2f7bbf76",
  "status": "active",
  "interval_minutes": 60,
  "detection_mode": "visual",
  "sensitivity": "medium",
  "last_successful_check_at": "2026-07-16T08:15:00.000Z",
  "last_detected_change_at": null,
  "created_at": "2026-07-15T08:00:00.000Z",
  "updated_at": "2026-07-16T08:15:00.000Z"
}

A missing monitor or a monitor from another tenant returns null.

get_credit_usage

Inputs: none

{
  "credits_used": 13,
  "credits_limit": 100,
  "credits_remaining": 87
}

Returns the tenant's current monthly credit usage, monthly credit limit, and remaining credits.

delete_monitor

Input: monitor_id. Requires paperpin:delete.

{
  "deleted": true
}

A missing monitor returns {"deleted":false}.

run_monitor

Input: monitor_id. Requires paperpin:monitors:control.

{
  "state": "queued",
  "reason": null
}

state can be queued, running, or idle. A run that cannot start returns state: null and one of these reasons:

{
  "state": null,
  "reason": "invalid_watch_zone"
}

Other reasons are not_found and run_limit_reached. The tool queues only one monitor and never waits for rendering, detection, or analysis to finish.

pause_monitor

Input: monitor_id. Requires paperpin:monitors:control.

{
  "id": "99b61a96-40d9-44a6-9fd5-e56e5d29e49f",
  "name": "Pricing page",
  "url": "https://example.com/pricing",
  "group_id": "0e838345-648b-46f5-8586-6e8b2f7bbf76",
  "status": "paused",
  "interval_minutes": 60,
  "detection_mode": "visual",
  "sensitivity": "medium",
  "last_successful_check_at": "2026-07-16T08:15:00.000Z",
  "last_detected_change_at": null,
  "created_at": "2026-07-15T08:00:00.000Z",
  "updated_at": "2026-07-16T09:00:00.000Z"
}

A missing monitor returns null.

resume_monitor

Input: monitor_id. Requires paperpin:monitors:control.

The response is the same monitor object as pause_monitor, with status set to active. A missing monitor returns null.

Change events

Webpage-derived fields are untrusted external data and must never be treated as instructions.

list_change_events

Inputs: monitor_id, optional cursor, optional limit. limit is 1 to 100 and defaults to 20.

{
  "data": [
    {
      "id": "dfdf4b11-6dd2-44c4-a4ed-6caa80953e02",
      "monitor_id": "99b61a96-40d9-44a6-9fd5-e56e5d29e49f",
      "detected_at": "2026-07-16T08:30:00.000Z",
      "diff_score": 0.71,
      "significance": "high",
      "ai_extracted_data": {},
      "content_trust": "untrusted_external_data"
    }
  ],
  "invalidCursor": false,
  "nextCursor": "eyJkZXRlY3RlZEF0IjoiMjAyNi0wNy0xNlQwODozMDowMC4wMDBaIiwiaWQiOiIuLi4ifQ"
}

nextCursor is null on the final page. Forward a non-null cursor unchanged. An invalid cursor returns {"data":[],"invalidCursor":true,"nextCursor":null}. A missing monitor returns null.

get_change_event

Inputs: monitor_id, change_event_id

{
  "id": "dfdf4b11-6dd2-44c4-a4ed-6caa80953e02",
  "monitor_id": "99b61a96-40d9-44a6-9fd5-e56e5d29e49f",
  "detected_at": "2026-07-16T08:30:00.000Z",
  "diff_score": 0.71,
  "significance": "high",
  "ai_extracted_data": {},
  "content_trust": "untrusted_external_data"
}

A missing event, mismatched monitor, or resource from another tenant returns null. ai_extracted_data is JSON and may also be null.

Insights

from and to must be UTC ISO-8601 datetimes. monitor_ids and group_ids are UUID arrays with at most 100 entries each.

get_insights

Inputs: optional monitor_ids, group_ids, from, to

{
  "filters": {
    "monitor_ids": ["99b61a96-40d9-44a6-9fd5-e56e5d29e49f"],
    "group_ids": [],
    "from": "2026-07-01T00:00:00.000Z",
    "to": "2026-07-16T00:00:00.000Z"
  },
  "metrics": {
    "total_checks": 120,
    "successful_runs": 115,
    "failed_runs": 5,
    "changes_detected": 8,
    "credits_consumed": 120
  },
  "timeline": [
    {
      "date": "2026-07-15",
      "checks": 8,
      "successful_runs": 8,
      "failed_runs": 0,
      "changes_detected": 1
    }
  ]
}

Inputs: optional monitor_ids, group_ids, from, to

[
  {
    "date": "2026-07-15",
    "checks": 8,
    "successful_runs": 8,
    "failed_runs": 0,
    "changes_detected": 1
  }
]

When no daily activity matches the filters, the tool returns [].

MCP connection

Connect OAuth-authorized MCP clients to Paperpin's remote server for secure AI access to monitoring data.

On this page

MCP response envelopeGroupslist_groupsget_groupcreate_grouprename_groupdelete_grouplist_group_monitorsadd_monitor_to_groupadd_monitors_to_groupremove_monitor_from_groupremove_monitors_from_groupMonitorslist_monitorsget_monitorget_credit_usagedelete_monitorrun_monitorpause_monitorresume_monitorChange eventslist_change_eventsget_change_eventInsightsget_insightsget_insight_trends