Tool reference

Every kind of MCP tool ShipMCP generates, when it appears, and what it expects. For the generator's rules see Tool generation.

Read tools

Generated for every table on every endpoint, no scope required.

list_<table>

Paginated row listing. Sorted by the table's most useful date column descending when one exists, otherwise by primary key ascending. order: "asc" | "desc" arg flips direction when the table has a date column.

{ "limit": 20, "offset": 0, "order": "desc" }
// → "[ { "id": 1, "title": "...", ... }, ... ]"

get_<table>_by_<idColumn>

Single-row lookup by primary key. The idColumn in the tool name reflects the actual PK name (usually id, sometimes uuid, etc.).

{ "id": 42 }
// → "[ { "id": 42, ... } ]" (one row or empty)

search_<table>

ILIKE-based full-text search across every text column on the table. Generated only when the table has at least one text column. The tool description lists the searched columns.

{ "query": "ship", "limit": 20 }
// → rows where any text column contains "%ship%"

filter_<table>

Unified filter. Properties depend on the table's columns:

• Low-cardinality text → exact match: { "status": "active" }
• Numeric → range pair: { "min_price": 10, "max_price": 100 }
• Boolean → exact: { "is_published": true }
• Date/timestamp → range pair: { "created_at_after": "2026-01-01", "created_at_before": "2026-02-01" }

count_<table>_by_<column>

GROUP BY count. Generated only for low-cardinality text columns (≤50 distinct values). Returns [{ "value": "...", "count": N }, ...] sorted by count descending. No arguments.

Cross-table joins

get_<children>_for_<parent_singular>

Generated for every foreign-key relationship. Lists rows from the child table that point at a specific parent row.

// e.g. get_links_for_document
{ "document_id": 1, "limit": 20 }
// → all links rows where document_id = 1

Resource tools

get_<table>_file

Generated only when the table has a source_r2_key column (today: just documents, when keep_originals=1). Returns a 120-second signed URL pointing at the original uploaded file. Agents can follow the URL with a plain GET; no auth needed.

{ "id": 1 }
// → "Download URL (valid 120s):
//    https://mcp.shipmcp.io/<slug>/files?t=eyJ...
//    Title: ..., Size: 9.9 MB, Content-Type: audio/mpeg"

resources/list and resources/read (MCP methods)

Functionally adjacent to get_<table>_file but invoked as JSON-RPC methods rather than tool calls. Agents that speak the resources/* spec (Claude Desktop, Cursor, MCP Inspector) prefer these — files ≤ 4 MB inline as base64; larger files come back as a text block with a signed URL. URI format: shipmcp://<slug>/<documentId>.

Write tools Pro+ writeable endpoints

Generated only when endpoints.allow_writes = 1 AND the table has a single-column primary key. Require the mcp:write OAuth scope. All three are asynchronous — return {"status":"queued","job_id":"..."} immediately; poll with get_write_job_by_id.

Metadata tables (pdf_metadata, audio_metadata, image_metadata, office_metadata, web_metadata) are excluded — they're populated by the ingest pipeline.

insert_<table>

Add a row. Argument schema mirrors the table's writable columns; required fields are NOT NULL columns without defaults. Server-managed columns (timestamps with NOW() defaults, autoincrement IDs) are accepted but optional.

{ "title": "Note", "content": "...", "url": "note://1", "kind": "text" }
// → "{ \"status\": \"queued\", \"job_id\": \"abc-123\" }"
// poll later for: { "id": 42 }

update_<table>_by_<idColumn>

Patch-style update by primary key. Pass the id plus only the columns you want to change; others are left alone (JSON Merge Patch shape).

{ "id": 42, "frontmatter": { "viewed_at": "2026-04-28T..." } }
// → queued; later: { "id": 42 }

delete_<table>_by_<idColumn>

Remove a row by primary key. Irreversible.

{ "id": 42 }
// → queued; later: { "id": 42 } if found, or failed with error

Built-in ingest tools Pro+ writeable endpoints

Same scope/flag/plan gates as write tools. Async — return a job_id; the agent can poll. See Agent writes & ingest for the full mental model.

ingest_url

Fetch a URL with Cloudflare Browser Rendering and merge into the corpus.

{ "url": "https://example.com/article", "format": "markdown" }
{ "url": "https://docs.example.com",   "format": "crawl", "max_depth": 2, "max_pages": 50 }
{ "url": "https://example.com/list",   "format": "json",  "table_name": "products" }

ingest_file

Inline base64. Capped at ~7 MB to avoid Worker memory limits at decode. Larger files: request_upload_url.

{ "filename": "notes.pdf", "content_base64": "JVBERi0...", "mime_type": "application/pdf" }

request_upload_url + ingest_uploaded_file

Two-step large-file path. Step 1 mints a 5-minute signed PUT URL; step 2 kicks ingestion against the uploaded R2 key.

// 1. Mint
request_upload_url({ "filename": "podcast.mp3" })
// → { "upload_url": "...", "r2_key": "uploads/.../podcast.mp3", "expires_in": 300 }

// 2. Caller PUTs bytes to upload_url (no auth header needed)
PUT <upload_url>
Content-Type: audio/mpeg
<binary body>

// 3. Kick ingestion
ingest_uploaded_file({ "r2_key": "uploads/.../podcast.mp3" })

Polling tool

get_write_job_by_id

The async sibling of every write/ingest tool. Pass the job_id you got back; returns the current status (queued | running | succeeded | failed) and, on success, the result payload (row id for writes; rows-inserted + tables for ingests).

{ "job_id": "abc-123" }
// → {
//     "job_id": "abc-123",
//     "tool": "insert_documents",
//     "status": "succeeded",
//     "result": { "id": 42 },
//     "enqueued_at": "...", "completed_at": "..."
//   }

How to find your endpoint's exact tool list

Two ways:

• Dashboard: open /endpoints/<id> → the Generated MCP tools card lists every tool with its description.
• JSON-RPC: call tools/list on your endpoint:

POST https://mcp.shipmcp.io/<your-slug>/mcp
Authorization: Bearer smcp_...
Content-Type: application/json

{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }

See MCP protocol for the full envelope. To refresh the manifest after enabling a feature, use the Rebuild button on the Tools list card or toggle "Allow agent writes" off and on.