API & MCP
MCP tools & resources
Once a client is connected, it has these tools and resources. You rarely call them by hand — the AI client chooses them to answer your questions — but knowing what's available (and what's off-limits) helps you ask for the right things.
Tools#
Discovery#
| Tool | Does | Key inputs |
|---|---|---|
list_projects | List the organisation's projects | search, limit (≤500), page |
get_project | Project details by id | project_id |
list_datasets | Datasets in a project | project_id, limit, page |
get_dataset_info | The primary inspection tool — full metadata, columns, and optionally statistics and sample rows | dataset_id, include_statistics, include_sample_rows (≤100) |
Query#
| Tool | Does | Key inputs |
|---|---|---|
execute_sql | Run read-only SQL and return rows | query, limit (default 10, ≤1,024), snapshot_version |
get_query_count | Count matching rows without fetching them | query, snapshot_version |
execute_sql enforces the same allowlist as the REST API — only SELECT, WITH, DESCRIBE and SUMMARIZE. It caps results at 1,024 rows, truncates very large payloads at ~50,000 characters, and times out at 30 seconds. snapshot_version reads a dataset as of a past version.
Management#
| Tool | Does | Key inputs |
|---|---|---|
create_project | Create a project | name, description |
get_upload_url | A presigned URL to upload a file | filename, project_id |
create_dataset | Ingest a file from a URL into a queryable dataset | project_id, name, description, url, column_descriptions |
Create a dataset#
create_dataset is a genuine write path — it's how an assistant turns a file into a queryable dataset. It pairs with get_upload_url in a three-step recipe:
Get an upload URL.
get_upload_url(filename, project_id)returns a presignedupload_url(valid one hour) and thes3_urlthe file will live at.Upload the file.
PUTthe raw bytes toupload_url.Create the dataset.
create_dataset(project_id, name, description, url = s3_url, column_descriptions = {…})ingests the file into a new dataset, records it, and — on success — deletes the uploaded source file. Provide a description for every column; malformed column names are auto-fixed to snake_case.
For a file already reachable at a public URL, you can skip the first two steps and pass that URL to create_dataset directly.
Resources#
Resources are browsable data an MCP client can read without a tool call:
| Resource | Returns |
|---|---|
gopie://projects | every project in the organisation |
gopie://project/{project_id}/datasets | the datasets in one project |
gopie://dataset/{dataset_id}/schema | a dataset's columns and types |
All three return JSON. Clients that support resource browsing surface these as an explorable tree; others reach the same data through the discovery tools above.
Built-in guidance#
Every session, the server sends the client an instructions block tailored to your deployment: your organisation id and SQL tips — conveniences like SELECT * EXCLUDE (…) and SUMMARIZE. It also spells out the read-only constraint and the recommended workflow (list projects → list datasets → inspect a dataset → query). That's why a connected assistant tends to write SQL that runs correctly the first time.