MCP Reference
Overview
Posit Connect includes a built-in Model Context Protocol (MCP) server for managing content. Clients connect to /mcp/ over the Streamable HTTP transport as a Connect user. Tool calls run with the permissions assigned to that user. See Connect MCP in the user guide to connect a client and Connect MCP in the admin guide to configure the server.
Agents obtain workflow guidance through get_server_skill.
The following reference lists each tool’s description, behavior, parameters, and return fields.
Nested fields are required only when their parent object or array item is present.
create_content
Create a content item and return its GUID and publishing URLs.
This tool adds new items and does not change existing content.
Parameters
Additional properties are not allowed
| Parameter | Type | Required | Details |
|---|---|---|---|
name |
string |
Yes | Lowercase hyphenated name for the new content |
title |
string |
No | Display title for the new content |
Return fields
Additional properties are not allowed
| Field | Type | Required | Details |
|---|---|---|---|
content_url |
string |
Yes | |
dashboard_url |
string |
Yes | |
guid |
string |
Yes | |
name |
string |
Yes | |
title |
string |
Yes | |
url_templates |
object |
Yes | Additional properties are not allowed |
url_templates.dashboard |
string |
Yes | |
url_templates.logs |
string |
Yes | |
url_templates.settings |
string |
Yes |
deploy_bundle
Deploy an uploaded bundle and return its task identifier and publishing URLs.
This tool can change existing content, such as the active bundle.
Parameters
Additional properties are not allowed
| Parameter | Type | Required | Details |
|---|---|---|---|
bundle_id |
string |
Yes | Identifier of the uploaded bundle |
guid |
string |
Yes | GUID of the content to deploy |
Return fields
Additional properties are not allowed
| Field | Type | Required | Details |
|---|---|---|---|
content_url |
string |
Yes | |
dashboard_url |
string |
Yes | |
guid |
string |
Yes | |
task_id |
string |
Yes | |
url_templates |
object |
Yes | Additional properties are not allowed |
url_templates.dashboard |
string |
Yes | |
url_templates.logs |
string |
Yes | |
url_templates.settings |
string |
Yes |
download_bundle
Return a full deployment archive download URL and five-minute token for any content, including pins. Requires at least Reviewer access to the content. GET the URL with X-Posit-Bundle-Download-Token; the archive GET consumes the token. Save and extract the archive locally to inspect or edit source. To redeploy, use request_bundle_upload and deploy_bundle; editing requires Collaborator access. For pin data alone use inspect_pin and request_pin_download. Archive bytes do not pass through MCP.
This tool adds new items and does not change existing content.
Parameters
Additional properties are not allowed
| Parameter | Type | Required | Details |
|---|---|---|---|
bundle_id |
string |
No | Historical bundle ID; omission selects the active bundle |
content_guid |
string |
Yes | Content GUID returned by find_content or search_pins |
Return fields
Additional properties are not allowed
| Field | Type | Required | Details |
|---|---|---|---|
bundle_id |
string |
Yes | |
content_guid |
string |
Yes | |
download_url |
string |
Yes | Absolute URL to GET once with the returned token header; save the response locally |
expires_at |
string |
Yes | RFC3339 expiration five minutes after issuance; a matching pin-file GET consumes the token before content authorization; archive GET consumes it after authorization |
header_name |
string |
Yes | |
path |
string |
No | |
token |
string |
Yes | Single-use credential scoped to the selected archive or pin file; send in header_name, never in a URL |
find_content
Find content the caller can access. Supply content_guid for one exact item, or omit it to list and search content with q. See the q input description for the complete filter list and query syntax. Every result is a compact discovery summary and includes tag names. Results are paginated.
This tool is read-only.
Parameters
Additional properties are not allowed
| Parameter | Type | Required | Details |
|---|---|---|---|
content_guid |
string |
No | Exact content GUID. Cannot be combined with search or pagination fields. Format: uuid |
order |
string |
No | Allowed values: asc, desc |
page_number |
integer |
No | Result page. Zero or omission uses the default of 1; negative values are rejected. Minimum: 0 |
page_size |
integer |
No | Results per page. Zero or omission uses the default of 20; negative values or values above 500 are rejected. Maximum: 500Minimum: 0 |
q |
string |
No | Connect content search query. Free text matches name, title, and description. Shared filters: access:, created:, image:, integration:, locked:, nodejs:, package:, published:, python:, quarto:, r:, scheduled:, source_updated:, tag:, type:, and updated:. Additional filters: bookmarked:, involves:, and owner:. Separate multiple values with commas and quote values containing spaces or commas. Boolean filters support is:<field> and not:<field>; prefix any filter or term with - to negate it. Runtime filters accept version comparisons; date filters accept RFC3339 values, ranges, comparisons, and @today offsets. Empty or omitted lists accessible content. |
sort |
string |
No | Allowed values: created_time, last_deployed_time, name, title |
Return fields
| Field | Type | Required | Details |
|---|---|---|---|
current_page |
integer |
Yes | Minimum: 1 |
results |
array |
Yes | Compact content summaries intended for discovery. |
results[] |
object |
Not applicable | Additional properties are not allowed |
results[].access_type |
string |
Yes | Allowed values: all, logged_in, acl |
results[].app_mode |
string |
Yes | |
results[].app_role |
string |
No | Allowed values: none, viewer, reviewer, editor, owner |
results[].content_category |
string |
Yes | |
results[].content_url |
string |
Yes | Format: uri |
results[].created_time |
string |
Yes | Format: date-time |
results[].dashboard_url |
string |
Yes | Format: uri |
results[].description |
string |
Yes | Maximum length: 4096 |
results[].guid |
string |
Yes | Format: uuid |
results[].last_deployed_time |
string or null |
Yes | Format: date-time |
results[].locked |
boolean |
Yes | |
results[].locked_message |
string |
No | |
results[].name |
string |
Yes | |
results[].tags |
array |
Yes | |
results[].tags[] |
string |
Not applicable | |
results[].title |
string or null |
Yes | |
total |
integer |
Yes | Minimum: 0 |
warnings |
array |
No | |
warnings[] |
string |
Not applicable |
get_deployment_status
Wait up to 20 seconds for a deployment task and return task status, output, log cursors, and content URLs.
This tool is read-only.
Parameters
Additional properties are not allowed
| Parameter | Type | Required | Details |
|---|---|---|---|
content_guid |
string |
Yes | GUID of the content being deployed. Format: uuid |
first |
integer |
No | First log line to return; use last from the previous response to continue. Default: 0Minimum: 0 |
task_id |
string |
Yes | Deployment task identifier. |
wait |
integer |
No | Seconds to wait for completion; defaults to 5 and cannot exceed 20. Default: 5Maximum: 20Minimum: 0 |
Return fields
Additional properties are not allowed
| Field | Type | Required | Details |
|---|---|---|---|
code |
integer |
Yes | Maximum: 2.147483647e+09Minimum: -2.147483648e+09 |
content_url |
string |
No | |
dashboard_url |
string |
No | |
error |
string |
Yes | |
finished |
boolean |
Yes | |
last |
integer |
Yes | Maximum: 2.147483647e+09Minimum: -2.147483648e+09 |
output |
null or array |
No | |
output[] |
string |
Not applicable | |
task_id |
string |
Yes | |
url_templates |
null or object |
No | Additional properties are not allowed |
url_templates.dashboard |
string |
Yes | |
url_templates.logs |
string |
Yes | |
url_templates.settings |
string |
Yes |
get_server_skill
Return the Posit Connect MCP skill: workflows, tool order, permissions, and manifest rules for this server’s tools. Load it before your first Connect tool call when the user wants to: find or inspect content on Connect; search, inspect, or download pin data; download, edit, and redeploy a content bundle; publish or deploy a project to Connect, such as a Python or R app or API, Shiny, Quarto, R Markdown, Jupyter, Node.js, or a static site; publish an HTML, Markdown, or Quarto document from context; write a manifest.json for Connect; or check a deployment’s status and logs. Load this only if guidance for these tools is not already in your context.
This tool is read-only.
Parameters
Additional properties are not allowed
This tool takes no inputs.
Return fields
Additional properties are not allowed
| Field | Type | Required | Details |
|---|---|---|---|
skill |
string |
Yes | Connect MCP tool instructions in Markdown |
inspect_pin
Inspect a pin’s data.txt metadata and list every dataset file with its full download URL and size when available. Requires at least Viewer access. Use request_pin_download with this bundle_id for a single-use token per data file; path can be omitted for a one-file pin. For a source archive to edit and redeploy, use download_bundle (Reviewer access).
This tool is read-only.
Parameters
Additional properties are not allowed
| Parameter | Type | Required | Details |
|---|---|---|---|
bundle_id |
string |
No | Optional historical bundle ID; omission selects the active bundle |
content_guid |
string |
Yes | GUID returned by search_pins |
Return fields
Additional properties are not allowed
| Field | Type | Required | Details |
|---|---|---|---|
bundle_id |
string |
Yes | |
content_guid |
string |
Yes | |
files |
null or array |
Yes | |
files[] |
object |
Not applicable | Additional properties are not allowed |
files[].download_url |
string |
Yes | |
files[].path |
string |
Yes | |
files[].size |
null or integer |
No | |
metadata |
string |
No | |
metadata_status |
string |
No | |
metadata_url |
string |
Yes |
ping
Verify the MCP connection is working end-to-end. Returns pong.
This tool is read-only.
Parameters
Additional properties are not allowed
This tool takes no inputs.
Return fields
Additional properties are not allowed
| Field | Type | Required | Details |
|---|---|---|---|
reply |
string |
Yes | Always the string pong |
publish_static_content
Create or update a static HTML, Markdown, or Quarto content item, upload the text as a Connect bundle, and start its deployment. Poll get_deployment_status with the returned task_id and content_guid.
This tool can change existing content, such as the active bundle.
Parameters
Additional properties are not allowed
| Parameter | Type | Required | Details |
|---|---|---|---|
content |
string |
Yes | UTF-8 text to publish |
file_name |
string |
Yes | Relative bundle path, for example index.html or report.qmd |
guid |
string |
No | Existing content GUID; when supplied, name and title are ignored |
name |
string |
No | Lowercase hyphenated name for new content |
title |
string |
No | Display title for new content |
Return fields
Additional properties are not allowed
| Field | Type | Required | Details |
|---|---|---|---|
bundle_id |
string |
Yes | Identifier of the uploaded bundle |
content_guid |
string |
Yes | GUID of the published content |
content_url |
string |
Yes | |
dashboard_url |
string |
Yes | |
task_id |
string |
Yes | Identifier of the deployment task |
url_templates |
object |
Yes | Additional properties are not allowed |
url_templates.dashboard |
string |
Yes | |
url_templates.logs |
string |
Yes | |
url_templates.settings |
string |
Yes |
request_bundle_upload
Mint a short-lived, single-use upload token for an existing piece of content. Returns the existing bundle archive upload endpoint and a token to send as X-Posit-Bundle-Upload-Token: <token>. The token is bound to the supplied content GUID, expires in 5 minutes, and is consumed on first use. The caller must already have publisher rights on the target content.
This tool adds new items and does not change existing content.
Parameters
Additional properties are not allowed
| Parameter | Type | Required | Details |
|---|---|---|---|
guid |
string |
Yes | GUID of the existing content to upload a bundle for |
Return fields
Additional properties are not allowed
| Field | Type | Required | Details |
|---|---|---|---|
expires_at |
string |
Yes | RFC3339 timestamp at which the token stops working |
token |
string |
Yes | Single-use token; pass as the X-Posit-Bundle-Upload-Token header |
upload_url |
string |
Yes | Absolute URL of the archive and static bundle upload endpoint |
request_pin_download
Return one pin data file’s download URL and a single-use token valid for five minutes. Requires at least Viewer access. Omit path when the pin has one data file. For multiple files, pass a path from inspect_pin and request a token for each file. Pass the inspected bundle_id to keep downloads on that revision. GET the URL once with X-Posit-Bundle-Download-Token and save locally. The token is bound to that content, revision, and file path; it cannot download another file or source archive. Metadata comes from inspect_pin; file bytes do not pass through MCP. Use download_bundle for archives (Reviewer access).
This tool adds new items and does not change existing content.
Parameters
Additional properties are not allowed
| Parameter | Type | Required | Details |
|---|---|---|---|
bundle_id |
string |
No | Historical bundle ID; omission selects the active bundle |
content_guid |
string |
Yes | Pin content GUID returned by search_pins |
path |
string |
No | Data file path from inspect_pin; omit when the pin has exactly one data file |
Return fields
Additional properties are not allowed
| Field | Type | Required | Details |
|---|---|---|---|
bundle_id |
string |
Yes | |
content_guid |
string |
Yes | |
download_url |
string |
Yes | Absolute URL to GET once with the returned token header; save the response locally |
expires_at |
string |
Yes | RFC3339 expiration five minutes after issuance; a matching pin-file GET consumes the token before content authorization; archive GET consumes it after authorization |
header_name |
string |
Yes | |
path |
string |
No | |
token |
string |
Yes | Single-use credential scoped to the selected archive or pin file; send in header_name, never in a URL |
search_pins
Search viewer-accessible Connect pins, which are static data items. Returns the Connect content GUID and, when owner details are visible, the owner/name pin identifier for use with the R or Python pins package. Results are limited to 20 per page.
This tool is read-only.
Parameters
Additional properties are not allowed
| Parameter | Type | Required | Details |
|---|---|---|---|
page_number |
integer |
No | One-based result page; zero or omission selects the first page |
page_size |
integer |
No | Results per page; defaults to 20 and cannot exceed 20 |
query |
string |
No | Search terms for pin names, titles, or descriptions; omit to list accessible pins |
Return fields
Additional properties are not allowed
| Field | Type | Required | Details |
|---|---|---|---|
current_page |
integer |
Yes | |
results |
null or array |
Yes | |
results[] |
object |
Not applicable | Additional properties are not allowed |
results[].active_bundle_id |
string |
No | |
results[].content_guid |
string |
Yes | |
results[].content_url |
string |
Yes | |
results[].description |
string |
Yes | |
results[].last_deployed_time |
null or string |
Yes | |
results[].name |
string |
Yes | |
results[].owner_username |
string |
No | |
results[].pin_name |
string |
No | |
results[].title |
null or string |
Yes | |
total |
integer |
Yes | |
warnings |
null or array |
No | |
warnings[] |
string |
Not applicable |