---
title: "MCP tools"
description: "Reference for the 14 tools the Pallyy MCP server exposes to AI assistants: social sets, post sets, media, media uploads, and calendar notes, with every input."
category: "mcp"
emoji: "🧰"
order: 2
datePublished: "2026-09-04"
dateUpdated: "2026-09-04"
---

The Pallyy [MCP server](/docs/api/mcp) exposes 14 tools, each backed by one REST endpoint. A tool's result is the endpoint's JSON response, so the objects an assistant reads are the ones documented on the [social sets](/docs/api/social-sets), [post sets](/docs/api/post-sets), [media](/docs/api/media), [media uploads](/docs/api/media-uploads), and [notes](/docs/api/notes) pages.

Read tools work on every connection. Write tools need the scope listed next to them, see [authentication](/docs/api/authentication). Dates are ISO 8601 strings with a timezone offset, for example `2026-09-14T09:00:00+10:00`.

## All tools

| Tool | What it does | Scope |
| --- | --- | --- |
| [`list_social_sets`](#list_social_sets) | List the social sets the connection can access | Read |
| [`get_social_set`](#get_social_set) | Get one social set with its accounts | Read |
| [`list_post_sets`](#list_post_sets) | List a social set's post sets, with filters | Read |
| [`get_post_set`](#get_post_set) | Get one post set with every network's post | Read |
| [`create_post_set`](#create_post_set) | Create a draft or scheduled post set | `post-sets:write` |
| [`update_post_set`](#update_post_set) | Change a post set's time, status, approval, or posts | `post-sets:write` |
| [`list_media`](#list_media) | List a social set's media library | Read |
| [`get_media`](#get_media) | Get one media item | Read |
| [`create_media_upload`](#create_media_upload) | Import a file from a URL into the library | `media:write` |
| [`get_media_upload`](#get_media_upload) | Check an import's status | Read |
| [`list_notes`](#list_notes) | List calendar notes in a date range | Read |
| [`get_note`](#get_note) | Get one calendar note | Read |
| [`create_note`](#create_note) | Pin a note to a date | `notes:write` |
| [`update_note`](#update_note) | Change a note's text, colour, or date | `notes:write` |

Scheduling a post set (`status` of `SCHEDULED`) also needs `post-sets:publish`.

## All tools at a glance

| Tool | What it does | Needs |
| --- | --- | --- |
| [list_social_sets](#list-social-sets) | Lists the social sets the connection can access, with their accounts | Read |
| [get_social_set](#get-social-set) | Gets one social set | Read |
| [list_post_sets](#list-post-sets) | Lists a social set's posts, filtered by date, status, approval, or caption | Read |
| [get_post_set](#get-post-set) | Gets one post set with every network's post and publish results | Read |
| [create_post_set](#create-post-set) | Creates a draft or scheduled post set for one or more networks | `post-sets:write`, plus `post-sets:publish` to schedule |
| [update_post_set](#update-post-set) | Changes a post set's time, status, approval, or posts | `post-sets:write`, plus `post-sets:publish` to schedule |
| [list_media](#list-media) | Browses a social set's media library | Read |
| [get_media](#get-media) | Gets one media item with its URL | Read |
| [create_media_upload](#create-media-upload) | Imports an image or video into the library from a URL | `media:write` |
| [get_media_upload](#get-media-upload) | Checks an import's status and gets its media library id | Read |
| [list_notes](#list-notes) | Lists a social set's calendar notes in a date range | Read |
| [get_note](#get-note) | Gets one calendar note | Read |
| [create_note](#create-note) | Creates a note pinned to a date, optionally repeating | `notes:write` |
| [update_note](#update-note) | Changes a note's text, colour, or date | `notes:write` |

## Social sets

Most other tools take a `socialSetId`, so an assistant usually starts here.

### list_social_sets

Lists the social sets the connection can access, each with its connected accounts. Takes no input and calls `GET /v1/social-sets`.

### get_social_set

Gets one social set with its connected accounts. Calls `GET /v1/social-sets/{id}`.

| Input | Required | Meaning |
| --- | --- | --- |
| `id` | Yes | The social set id |

## Post sets

A post set is one slot on the schedule: a date, a status, and one post per network it targets.

Every post set can be opened in Pallyy with a link built from its `socialSetId` and `id`, so an assistant can hand you a link to a post it found, created, or updated:

```
https://app.pallyy.com/dashboard/scheduling/calendar/month?set=<socialSetId>&post=<postSetId>
```

### list_post_sets

Lists a social set's post sets. Calls `GET /v1/post-sets` with the filters below; results are paginated as described on the [pagination](/docs/api/pagination) page.

| Input | Required | Meaning |
| --- | --- | --- |
| `socialSetId` | Yes | The social set to list |
| `startDate` | No | Only sets scheduled at or after this time |
| `endDate` | No | Only sets scheduled before this time |
| `status` | No | Array of `DRAFT`, `SCHEDULED`, `PUBLISHING`, `PUBLISHED` |
| `approval` | No | Array of `NONE`, `PENDING`, `EXTERNAL_PENDING`, `APPROVED`, `DENIED` |
| `search` | No | Caption text search, at least 3 characters |
| `page` | No | Zero-based page number |
| `size` | No | Page size, 1 to 100 |

### get_post_set

Gets one post set with every network's post, captions, media, and publish results. Calls `GET /v1/post-sets/{id}`.

| Input | Required | Meaning |
| --- | --- | --- |
| `id` | Yes | The post set id |

### create_post_set

Creates a post set. Requires `post-sets:write`, and `post-sets:publish` as well when `status` is `SCHEDULED`. Calls `POST /v1/post-sets`.

| Input | Required | Meaning |
| --- | --- | --- |
| `socialSetId` | Yes | The social set the post belongs to |
| `scheduledAt` | Yes | The time the post is scheduled or pinned to |
| `status` | Yes | `DRAFT` saves without publishing, `SCHEDULED` publishes at `scheduledAt` |
| `approval` | No | Review state, defaults to `NONE`. Anything else needs approvals on the plan |
| `posts` | Yes | One object per targeted network, at least one |

Each entry in `posts` follows the [create post set](/docs/api/post-sets#create-a-post-set) body: an `accountType`, a `caption`, a `media` array referencing library items by `mediaLibraryId`, and the network's own fields such as `type` and `collaborators` for Instagram or `title` and `privacy` for YouTube. The tool's input schema spells out every per-network shape, so a client validates the call before it reaches Pallyy, and the API's own validation message comes back on anything it still rejects.

One post set can target several networks at once. Publishing the same content to Instagram and LinkedIn is one call with two entries in `posts`, each carrying its own caption and media.

### update_post_set

Partially updates a post set: omitted fields keep their saved values. Requires `post-sets:write`, plus `post-sets:publish` when the set is or becomes `SCHEDULED`. Calls `PATCH /v1/post-sets/{id}`.

| Input | Required | Meaning |
| --- | --- | --- |
| `id` | Yes | The post set id |
| `scheduledAt` | No | New time for the set |
| `status` | No | `DRAFT` or `SCHEDULED` |
| `approval` | No | New review state |
| `posts` | No | One object per targeted network |

When `posts` is sent, each entry keeps a saved post by its `id` or replaces it, and each media entry either keeps a saved media by its embedded `id` or adds a library item by `mediaLibraryId`. Saved posts and media that aren't referenced are removed, so an assistant should fetch the set first and send the full list back. Sets that are publishing or published are read-only.

## Media

### list_media

Lists a social set's media library items. Calls `GET /v1/media`, paginated.

| Input | Required | Meaning |
| --- | --- | --- |
| `socialSetId` | Yes | The social set whose library to list |
| `folderId` | No | Only items in this folder |
| `type` | No | `image` or `video` |
| `name` | No | File name search |
| `page` | No | Zero-based page number |
| `size` | No | Page size, 1 to 100 |

### get_media

Gets one media library item with its URL and metadata. Calls `GET /v1/media/{id}`.

| Input | Required | Meaning |
| --- | --- | --- |
| `id` | Yes | The media item id |

### create_media_upload

Starts importing a file from a public URL into the social set's media library. Requires `media:write`. Calls `POST /v1/media-upload`.

| Input | Required | Meaning |
| --- | --- | --- |
| `socialSetId` | Yes | The social set whose library receives the file |
| `sourceUrl` | Yes | A publicly reachable `http` or `https` URL of the image or video, up to 2048 characters |

Processing is asynchronous. The tool returns the upload in status `CREATED`, and the assistant polls `get_media_upload` until it is `READY`, then uses the returned `mediaLibraryId` in a post.

### get_media_upload

Gets one upload's status: `CREATED`, `PROCESSING`, `READY` with the created `mediaLibraryId`, or `FAILED` with a `failureReason`. Calls `GET /v1/media-upload/{id}`.

| Input | Required | Meaning |
| --- | --- | --- |
| `id` | Yes | The upload id |

## Notes

### list_notes

Lists a social set's calendar notes in a date range. Both bounds are required and the range can span at most 366 days. Calls `GET /v1/notes`.

| Input | Required | Meaning |
| --- | --- | --- |
| `socialSetId` | Yes | The social set to list notes for |
| `startDate` | Yes | Range start |
| `endDate` | Yes | Range end |

### get_note

Gets one calendar note. Calls `GET /v1/notes/{id}`.

| Input | Required | Meaning |
| --- | --- | --- |
| `id` | Yes | The note id |

### create_note

Creates a note pinned to a date. Requires `notes:write`. Calls `POST /v1/notes`.

| Input | Required | Meaning |
| --- | --- | --- |
| `socialSetId` | Yes | The social set the note belongs to |
| `content` | Yes | The note text, up to 1000 characters |
| `hexColor` | Yes | One of `#faf785`, `#fff0db`, `#ffe5e5`, `#ffe4f7`, `#f2edff`, `#e1effc`, `#e4f8e2`, `#eee2d7`, `#f2f2f2` |
| `scheduledAt` | Yes | The time the note is pinned to |
| `repeat` | No | `{ "interval": "DAY" \| "WEEK" \| "MONTH" \| "YEAR", "occurrences": 2-100 }` to create a repeating series |

### update_note

Partially updates a note: omitted fields keep their saved values. Requires `notes:write`. Calls `PATCH /v1/notes/{id}`.

| Input | Required | Meaning |
| --- | --- | --- |
| `id` | Yes | The note id |
| `content` | No | The note text, up to 1000 characters |
| `hexColor` | No | One of the colours listed above |
| `scheduledAt` | No | The time the note is pinned to. Can't change on a repeating note or one imported from Google Calendar |

## Errors

A failed tool call returns an error result with the API's message, prefixed with the HTTP status:

```
Pallyy API error (404): Social set not found.
```

The messages and codes are the ones on the [errors](/docs/api/errors) page. Validation failures on a post set carry the API's per-post details, so an assistant can correct the specific caption or media entry that was rejected and try again.