MCP tool reference

This page is a reference for the Rowset MCP surface. Use Connect over MCP when you need setup steps.

Do not treat this page as the exact schema source. The connected MCP server's tool discovery response is the source of truth for live tool names, descriptions, and input schemas.

Startup tools

Use these tools at the beginning of an agent session:

get_user_info
get_rowset_capabilities

get_user_info verifies the authenticated Rowset account. get_rowset_capabilities returns current feature groups, recommended startup order, REST fallback paths, use-case patterns, and privacy guardrails.

Dataset discovery

Use these tools before creating a new dataset:

get_all_datasets
get_archived_datasets
search_datasets

Use search_rows when the relevant dataset is unknown or multiple datasets may contain the answer:

search_rows

When vector search is enabled, search_rows accepts natural-language search text, dataset or project filters, row field filters, archived filtering, sort, and limit. Results are hydrated from Rowset rows and include match metadata such as source, ranks, scores, point id, chunk index, and content hash. Rowset/Postgres remains the source of truth.

Project tools

Use projects to group related datasets by workflow, client, campaign, or agent task. Sections provide optional grouping inside a project.

get_all_projects
search_projects
create_project
get_project
get_project_sections
create_project_section
update_project
update_project_metadata
update_project_section
archive_project_section
archive_project

Archiving a project hides the project from normal project discovery. It does not delete or archive its datasets.

Use project metadata for source links, kickoff threads, planning docs, or other JSON context that should stay with the project. Pass an empty object to update_project_metadata to clear it. Passing an empty string for description to update_project clears the project description.

Dataset tools

Use create_dataset when the agent needs a new dataset:

create_dataset

Pass description, instructions, or metadata when the dataset should carry persistent operating context for future agent runs. Pass project_key to create the dataset inside a project, or pass both project_key and section_key to place it inside a project section.

For a specific active dataset, use:

get_dataset
list_dataset_rows
search_dataset_rows
get_dataset_row
get_dataset_row_by_index
create_dataset_row
update_dataset_row
update_dataset_row_by_index
delete_dataset_row
archive_dataset
restore_dataset

get_dataset returns dataset context, semantic column schema, and relationship summaries. Agents should call it before row operations.

Dataset and row tools enforce the authenticated user's ownership boundary. create_dataset, row mutation tools, and schema mutation tools change dataset contents, so agents should ask the user before using them unless the user explicitly requested the change.

Use archive_dataset when the user asks to remove a mistaken dataset. Archive keeps rows and schema metadata recoverable, hides the dataset from normal lists, and disables public preview sharing. Use get_archived_datasets to find archived dataset keys, then use restore_dataset to bring an archived dataset back.

Schema tools

Use schema tools when an existing active dataset needs columns changed without recreating it:

add_column
rename_column
drop_column
reorder_columns
update_dataset_metadata
update_dataset_project

Existing rows receive blank or default values when adding a column. Index columns cannot be dropped, and generated index columns cannot be renamed.

Use update_dataset_metadata when the user wants agents to remember dataset purpose, workflow rules, status conventions, or other JSON context without changing rows.

Use update_dataset_project when the user asks to organize or move a dataset between projects or into a project section. Pass section_key with project_key to assign a section. Passing null for project_key leaves the dataset ungrouped.

Relationship tools

Use relationships when one dataset stores another dataset row's index value.

list_dataset_relationships
create_dataset_relationship
resolve_dataset_relationship
delete_dataset_relationship

With enforcement enabled, row writes fail when a non-blank source value does not match an existing target row.

For typed reference cells, use {"type": "reference", "target": "dataset"} to store another Rowset dataset key or {"type": "reference", "target": "project"} to store a Rowset project key. Rowset validates non-blank values in the same account and stores canonical keys. When references are present, get_dataset includes dataset_references and project_references grouped by source column and target key.

Image asset tools

Use image columns when a row needs a private visual asset.

attach_image_to_dataset_row
get_dataset_image_asset

The hosted MCP server cannot read an agent's local file path. The agent must read local image bytes itself and pass base64 or a data URI. Rowset writes an opaque asset:{key} reference into the row cell.

attach_image_to_dataset_row accepts JPEG, PNG, or WebP bytes. Pass either row_id or the dataset index_value, not both. Use get_dataset_image_asset to retrieve asset metadata plus authenticated content_url and thumbnail_url values. Rowset normalizes image bytes before storage, so asset byte_size and checksum describe the stored Rowset file rather than the original file on disk.

Audio asset tools

Use audio columns when a row needs a private audio file.

attach_audio_to_dataset_row
get_dataset_audio_asset

The hosted MCP server cannot read an agent's local file path. The agent must read local audio bytes itself and pass base64 or a data URI. Rowset writes an opaque asset:{key} reference into the row cell.

attach_audio_to_dataset_row accepts MP3, WAV, M4A, AAC, Ogg, FLAC, or WebM bytes. Pass either row_id or the dataset index_value, not both. Use get_dataset_audio_asset to retrieve asset metadata plus authenticated content_url values. Rowset stores audio bytes privately without transcoding.

Public preview tools

Use public previews only when the user asks to share a read-only browser page:

update_dataset_public_preview

Public previews are not an authentication mechanism for agents or applications. Use authenticated MCP or REST for private row reads, writes, and exports. The tool returns the public preview URL when sharing is enabled.

Permissions

Agent API key permissions apply to MCP tools:

• Read keys can inspect account details, projects, datasets, rows, and exports.
• Read + write keys can create and update datasets, rows, projects, relationships, schema, and public preview settings.
• Admin keys can call create_agent_api_key to provision other agent API keys through REST or MCP.

Ask before destructive actions such as deleting rows, archiving datasets, or clearing public preview passwords.