MCP Tools — Overview
Access Rights
MCP tools are assigned to three scope levels:
| Scope | Meaning |
|---|---|
read | Read-only access; cannot create, edit, or delete |
write | Read and write sources, channels, and Inbox; no access to team settings |
admin | Full MCP access, including team settings |
For OAuth connections, the scope selected during authorization determines which tools can be accessed. For API tokens, the token role determines the maximum access level.
Workspace selection
The MCP server sits at https://picasi.app/mcp, with no Workspace in the address.
| Sign-in | Workspace |
|---|---|
| API token | fixed, the token’s Workspace; no parameter needed |
| OAuth | all Workspaces of the account; every call needs workspace_id |
With OAuth, list_workspaces returns the possible values. Without workspace_id the call is rejected.
Read Tools
All read tools require at least scope read.
search_updates
Searches updates by keywords, sources, tags, and time period.
Required Scope: read
| Parameter | Type | Description |
|---|---|---|
query | String | Full-text search term (optional) |
source_id | String | Updates from a specific source (optional) |
tags | Array | Topic tags to filter by (optional) |
folder | String | inbox, saved, or dropped (optional) |
source_ownership | String | all (default), own (only own sources), or competitor (only external sources) |
limit | Integer | Number of results (default: 20, max: 100) |
The source_ownership filter uses the is_own field at the source. It is the counterpart to the ownership filter in the Inbox UI and allows the AI assistant to specifically view only its own presence or only competitors.
get_update_details
Returns the full content of a single update.
Required Scope: read
| Parameter | Type | Description |
|---|---|---|
update_id | String | Update ID |
list_sources
Lists all sources in the Workspace.
Required Scope: read
| Parameter | Type | Description |
|---|---|---|
is_own | Boolean | true = own sources only, false = competitors only, omit = all |
Each returned source contains the is_own field so that AI assistants can distinguish between their own presence and that of competitors without having to make a second request.
Each channel comes with three fields that need to be kept apart:
| Field | Meaning |
|---|---|
monitoring_active | The switch of the channel: on or off. Not a health state. |
state | The state of retrieval: healthy, degraded, broken, quarantined or paused. Email channels are not fetched but receive; they report receiving, stale or waiting. null means no retrieval is attached yet. |
last_checked | The last fetch attempt, for email channels the message received last. |
For the full diagnosis of a single channel, get_channel_status is the tool.
list_reports
Lists available reports.
Required scope: read
| Parameter | Type | Description |
|---|---|---|
type | String | summary, feedback, list, linkedin_post, conversation_starters (optional) |
limit | Integer | Number (default: 10) |
get_report
Returns the complete content of a report.
Required scope: read
| Parameter | Type | Description |
|---|---|---|
report_id | String | Report ID |
get_team_context
Returns the AI context of the Workspace: team metadata (name, language, time zone), website URL, context documents, and ownership configuration.
Required scope: read
No required parameters.
The response contains the following in the context block:
website_url– stored organization URLis_own_sources_configured–true, as soon as at least one source is marked as its ownown_sources_count– number of its own sources
AI assistants should only offer Voice Share or Momentum comparisons if is_own_sources_configured is true — otherwise, there is no basis for comparison.
list_tags
Lists all tags in the Workspace.
Required scope: read
| Parameter | Type | Description |
|---|---|---|
type | String | sources, channels, updates (optional) |
get_update_statistics
Counts Updates instead of listing them. Takes the same filters as search_updates and has no cap of 100 results.
Required Scope: read
| Parameter | Type | Description |
|---|---|---|
group_by | String | source (default), source_tag, update_tag, day, week, month, quarter |
compare_previous_period | Boolean | Also counts the equally long preceding period and reports the difference |
query | String | Full-text search term (optional) |
source_id | String | Restrict to one source (optional) |
source_tags | Array | Source tags (optional) |
update_tags | Array | Topic tags (optional) |
source_ownership | String | all (default), own or competitor |
platform | String | Restrict to one platform, e.g. linkedin (optional) |
folder | Array | inbox, saved; the default is both |
days | Integer | Time range in days, 1 to 365 (default: 30) |
date_from, date_to | String | Time range as a date, instead of days |
Grouping by platform is not available. Dropped and overflow Updates are not counted.
get_channel_status
Returns the state of a channel: last fetch, last success, last error, number of consecutive failures, next scheduled attempt and the number of Updates from this channel.
Required Scope: read
| Parameter | Type | Description |
|---|---|---|
channel_id | String | Channel ID, from list_sources with include_channels=true |
discover_channels
Inspects a website and reports the channels that could be monitored. Creates nothing.
Required Scope: read
| Parameter | Type | Description |
|---|---|---|
url | String | Website to inspect (optional if source_id is set) |
source_id | String | Uses this source’s website and marks the channels it already has |
list_workspaces
Lists the Workspaces of the signed-in account with workspace_id, name and role.
Required Scope: none; the tool is open to every connection
No parameters.
Report Tools
create_report
Creates a report from the Updates matching a filter. The filters are the same as for search_updates.
Generation runs in the background: the call returns a request_id right away. get_report_status reports where it stands, get_report reads the finished report.
Required Scope: read
| Parameter | Type | Description |
|---|---|---|
type | String | Required. summary, feedback, list or conversation_starters |
title | String | Name of the report (optional) |
instructions | String | Focus for the AI (optional) |
language | String | Language code, e.g. de; the default is the Workspace language |
query | String | Full-text search term (optional) |
source_ids | Array | Restrict to these sources (optional) |
source_tags | Array | Source tags (optional) |
source_tags_mode | String | AND or OR |
update_tags | Array | Topic tags (optional) |
update_tags_mode | String | AND or OR |
source_ownership | String | all, own or competitor |
platform | String | Restrict to one platform (optional) |
folder | Array | Folders of the data basis; the default is inbox and saved |
days | Integer | Time range in days, 1 to 365 (default: 30) |
date_from, date_to | String | Time range as a date, instead of days |
get_report_status
Returns where a report ordered with create_report stands.
Required Scope: read
| Parameter | Type | Description |
|---|---|---|
request_id | String | The request_id from create_report |
| Status | Meaning |
|---|---|
queued | waiting in the queue |
running | being generated |
ready | finished; read it with get_report and the report_id |
empty | finished, but no Update matched the filters |
failed | aborted; the reason is in the answer |
Write Tools
All Write Tools require at least scope write.
create_source
Creates a new source.
Required Scope: write
| Parameter | Type | Description |
|---|---|---|
url | String | Source website URL |
name | String | Internal name |
tags | Array | Tag IDs (optional) |
update_source
Changes the name, URL, or tags of an existing source.
Required scope: write
| Parameter | Type | Description |
|---|---|---|
source_id | String | Source ID |
name | String | New name (optional) |
url | String | New URL (optional) |
delete_source
Deletes a source, including all channels and updates.
Required scope: write
| Parameter | Type | Description |
|---|---|---|
source_id | String | Source ID |
create_channel
Manually creates a channel.
Required scope: write
| Parameter | Type | Description |
|---|---|---|
source_id | String | Parent source ID |
url | String | Channel URL |
name | String | Channel name (optional) |
update_channel
Changes the name or description of a channel.
Required scope: write
| Parameter | Type | Description |
|---|---|---|
channel_id | String | Channel ID |
name | String | New name (optional) |
delete_channel
Deletes a channel.
Required scope: write
| Parameter | Type | Description |
|---|---|---|
channel_id | String | Channel ID |
toggle_channel
Enables or disables a channel.
Required Scope: write
| Parameter | Type | Description |
|---|---|---|
channel_id | String | Channel ID |
active | Boolean | true = active, false = inactive |
create_tag
Creates a new tag.
Required scope: write
| Parameter | Type | Description |
|---|---|---|
name | String | Tag Name |
type | String | sources, channels, or updates |
description | String | AI tagging description (optional) |
update_tag
Changes the name or description of a tag.
Required scope: write
| Parameter | Type | Description |
|---|---|---|
tag_id | String | Tag ID |
name | String | New name (optional) |
description | String | New AI description (optional) |
update_update_state
Moves Updates between the Workspace folders.
Required Scope: write
| Parameter | Type | Description |
|---|---|---|
update_ids | Array | Update IDs, at most 100 per call |
folder | String | inbox, saved or dropped |
The state applies per Workspace and does not change the Update itself. The answer reports each ID separately.
tag_update
Assigns existing topic tags to Updates.
Required Scope: write
| Parameter | Type | Description |
|---|---|---|
update_ids | Array | Update IDs, at most 100 per call |
tags | Array | Tags as slug, ID or name |
mode | String | add (default) keeps existing tags, replace sets exactly these |
Only tags with applies_to = updates are allowed; a source tag is refused. Create missing tags with create_tag first.
untag_update
Removes topic tags from Updates.
Required Scope: write
| Parameter | Type | Description |
|---|---|---|
update_ids | Array | Update IDs, at most 100 per call |
tags | Array | Tags to remove, as slug, ID or name |
Only this Workspace’s assignment is removed. The tag itself stays.
refresh_source_channels
Runs channel detection again for an existing source.
Required Scope: write
| Parameter | Type | Description |
|---|---|---|
source_id | String | Source ID |
create_detected | Boolean | false (default) only reports, true creates the missing channels |
Existing channels are not created twice; a deactivated channel counts as existing. New channels start fetching on their own.