sources operations
MCP tools and operation permissions for sources.
Generated from the shared operation catalog. Use the JSON catalog for complete input schemas. Required dependency checks can be stricter than the resource permission listed below.
source_promotion_schema_capture
Explicitly read bounded PostgreSQL/MySQL/MariaDB catalog metadata and save fresh promotion compatibility evidence. Does not read application rows, accept SQL or accept caller-supplied schema. Read purpose follows the configured read replica; write purpose checks the primary and additionally requires data Write. Requires source Read and SQL Run, current versioned credentials, a supported bounded adapter, and finishes or cancels within ten seconds. Returns observation counts and fingerprint only.
- HTTP:
POST /api/sources/:id/promotion-schema - SDK:
client.sources.capturePromotionSchema(input) - Access: workspace; sql / run
- Effect annotation: May change state or run effects
| Input | Requirement | Description |
|---|---|---|
purpose | Required | See schema |
id | Required | string |
source_databases_refresh
Refresh database names, connection readiness and setup choices for an unexpired connectionToken from source_databases_browse. Reuses the authenticated connection draft; does not create a database login or save a source.
- HTTP:
POST /api/sources/databases/refresh - SDK:
client.sources.refreshDatabases(input) - Access: workspace; source / write
- Effect annotation: May change state or run effects
| Input | Requirement | Description |
|---|---|---|
connectionToken | Required | string |
source_database_login_create
Explicitly create a read-only database login and grant it access to the selected discovered databases, optionally including future tables. Requires the setup connectionToken and administrative access through a saved server. Changes database access; generated credentials stay sealed and are not returned.
- HTTP:
POST /api/sources/databases/login - SDK:
client.sources.createDatabaseLogin(input) - Access: workspace; source / write
- Effect annotation: May change state or run effects
| Input | Requirement | Description |
|---|---|---|
connectionToken | Required | string |
databases | Required | array |
username | Required | string |
futureTables | Required | boolean |
source_databases_browse
Test a draft database connection and list its accessible databases before saving sources. Use source_kinds_list for connection fields; a saved server may supply the existing connection. Returns an expiring connectionToken for refresh, reader setup and source creation. Does not create a login or save a source.
- HTTP:
POST /api/sources/databases - SDK:
client.sources.browseDatabases(input) - Access: workspace; source / write
- Effect annotation: May change state or run effects
| Input | Requirement | Description |
|---|---|---|
kind | Required | string |
values | Optional | object |
fromContainer | Optional | string |
serverId | Optional | string |
dbHost | Optional | string |
dbPort | Optional | integer |
tunnel | Optional | object |
serverAccess | Optional | object |
source_list
List the data sources connected to this workspace.
- HTTP:
GET /api/sources - SDK:
client.sources.list(input) - Access: workspace; source / read
- Effect annotation: Read-only
See the JSON schema for this input contract.
source_kinds_list
List the data source kinds this build can connect, and the connection fields each one needs. Call this before POST /api/sources: the fields array gives the exact keys to send as values, which are required, their defaults, and which one is the secret. Kinds with ready: false have no driver in this build. tunnel.transports lists the tunnel transports this deployment permits; when it is empty, do not send a tunnel object — it will be refused.
- HTTP:
GET /api/sources/kinds - SDK:
client.sources.kinds(input) - Access: workspace; source / read
- Effect annotation: Read-only
See the JSON schema for this input contract.
source_write
Connect a data source. Call GET /api/sources/kinds first to learn which kinds this build implements and what fields each needs, then pass those as values. The connection is opened and verified before anything is stored, so a failure means nothing was written. Passwords are sealed in the secret store; a literal connection string is refused.
- HTTP:
POST /api/sources - SDK:
client.sources.create(input) - Access: workspace; source / write
- Effect annotation: May change state or run effects
| Input | Requirement | Description |
|---|---|---|
name | Required | string |
connectionToken | Optional | string |
database | Optional | string |
serverAccess | Optional | object |
kind | Required | string |
values | Optional | object |
secretRef | Optional | string |
fromContainer | Optional | string |
replicaValues | Optional | object |
replicaSecretRef | Optional | string |
tunnel | Optional | object |
serverId | Optional | string |
dbHost | Optional | string |
dbPort | Optional | integer |
replicaTarget | Optional | Replica endpoint as reached from the SSH server. Never reuses the primary forward. |
statementTimeoutMs | Optional | integer |
maxRows | Optional | integer |
maxBytes | Optional | integer |
concurrency | Optional | integer |
source_read
Read a saved data source, its public connection fields, limits and saved server association. Does not reveal passwords, private keys or secret values.
- HTTP:
GET /api/sources/:id - SDK:
client.sources.get(input) - Access: workspace; source / read
- Effect annotation: Read-only
| Input | Requirement | Description |
|---|---|---|
id | Required | string |
source_update
Edit a saved source name, connection fields, limits, replica reference or server/tunnel association. Omitted fields retain their stored values and secrets. New connection settings are checked by the normal source service; does not mutate source database records.
- HTTP:
PATCH /api/sources/:id - SDK:
client.sources.update(input) - Access: workspace; source / write
- Effect annotation: May change state or run effects
| Input | Requirement | Description |
|---|---|---|
name | Optional | string |
values | Optional | object |
replicaValues | Optional | See schema |
replicaSecretRef | Optional | See schema |
replicaTarget | Optional | See schema |
tunnel | Optional | See schema |
serverId | Optional | See schema |
dbHost | Optional | string |
dbPort | Optional | integer |
statementTimeoutMs | Optional | integer |
maxRows | Optional | integer |
maxBytes | Optional | integer |
concurrency | Optional | integer |
id | Required | string |
source_remove
Remove a saved data source connection from BytesMap and close its connection pool. Requires source Admin; managed dataset sources are removed through their dataset instead. Does not drop the external database or delete its records.
- HTTP:
DELETE /api/sources/:id - SDK:
client.sources.remove(input) - Access: workspace; source / admin
- Effect annotation: May change state or run effects; destructive operation
| Input | Requirement | Description |
|---|---|---|
id | Required | string |
source_schema_read
Read a source's tables, columns and relationships.
- HTTP:
GET /api/sources/:id/schema - SDK:
client.sources.schema(input) - Access: workspace; schema / read
- Effect annotation: Read-only
| Input | Requirement | Description |
|---|---|---|
id | Required | string |
source_stats_read
Read a source's live health and resource metrics: size, connections, cache hit rate, uptime.
- HTTP:
GET /api/sources/:id/stats - SDK:
client.sources.stats(input) - Access: workspace; source / read
- Effect annotation: Read-only
| Input | Requirement | Description |
|---|---|---|
id | Required | string |
source_sql_run
Run a query against a source and get rows back. Example input: {id:"SOURCE_ID", query:{kind:"native", sourceKind:"postgres", statement:"select id, name from customers limit 10"}}. query is an object, never a raw SQL string. Takes either the portable IR — {kind:'growth'|'row-count'|'top-values'|'histogram'|'chart'|'rows', …}, which this translates to whatever language the source speaks — or {kind:"native"} with a statement in the driver's own language. Results carry honesty flags: estimated, A chart or rows query may read a table, or a joined relation {base, joins}; joined fields use alias.column. sampled and truncated in meta must be surfaced, not dropped. meta.page says which slice you got; meta.totalRows is present only if you passed count:true, so absent means unknown rather than zero. Pass explain:true for meta.plan — the query as this engine received it, which is how you check what the IR compiled to. Pass chart:{title,spec} to display the result using the same encoding as chart_create. Channels refer to result column names. ClickHouse uses sourceKind:"clickhouse"; managed dataset sources expose only their scoped events relation.
- HTTP:
POST /api/sources/:id/query - SDK:
client.sources.run(input) - Access: workspace; sql / run
- Effect annotation: Read-only
| Input | Requirement | Description |
|---|---|---|
chart | Optional | Display returned data as a chart. Channels use result column names. Uses the chart_create encoding without saving a query or chart. |
query | Required | A bytesmap query. Either the portable IR — {kind:"growth"|"row-count"|"top-values"|"histogram"|"column-stats"|"orphans"|"chart"|"rows", …} — or the escape hatch {kind:"native", sourceKind:"<this source's kind>", statement:"…"}. A native statement is in the driver's own language: SQL for SQL engines, a JSON aggregation pipeline for MongoDB. It is refused if written for a different engine, if it writes, and is still subject to the row cap and statement timeout. For {kind:"chart"}: dimensions[].role is "group" (an axis, at most two) or "series" (a breakdown, at most one) — and when you use a series, set seriesLimit rather than relying on limit, because limit cuts ROWS of the joint group-by and can leave a series with only some of its buckets. measures[].filter is a per-measure WHERE, so sum(total) where status='paid' sits beside sum(total) in one query; having filters the aggregates and its leaves name measure aliases (m0, m1) rather than columns; offset pages; totals is "none"|"with"|"only" and "with" adds meta.totals, the same query ungrouped. from is a table ref or a derived relation {isDerived:true, statement, sourceKind, aggregated, columns} — your own SELECT as the FROM, which the rest of the query then groups, filters and pages normally. expression on a measure or dimension is a raw fragment in this engine's dialect; it is read-only-checked and makes the query non-portable to other engines. |
maxRows | Optional | integer |
count | Optional | Also return meta.totalRows: how many rows the query would return in total. Costs a second pass that scans everything the query touches, so ask for it only when the exact number is the point — meta.truncated already tells you whether more rows exist. |
explain | Optional | Also return meta.plan: the query as this engine received it — {form:"sql", sql, params} for a SQL source, {form:"mongo", collection, pipeline} for MongoDB. Costs nothing; the compiled artefact already exists. Placeholders are NOT substituted — params is listed separately, in order, because a statement with values spliced in is the one form this system never sends. |
id | Required | string |
source_keys_scan
Scan a key/value source. Continue with the returned cursor until it is "0", including after an empty page. count is a scan hint.
- HTTP:
POST /api/sources/:id/keys/scan - SDK:
client.sources.scanKeys(input) - Access: workspace; sql / run
- Effect annotation: Read-only
| Input | Requirement | Description |
|---|---|---|
cursor | Optional | string |
match | Optional | string |
count | Optional | integer |
id | Required | string |
source_key_read
Read a bounded key/value preview by the opaque key id from source_keys_scan. Includes key type, expiry, size, and whether the preview was truncated.
- HTTP:
POST /api/sources/:id/keys/read - SDK:
client.sources.readKey(input) - Access: workspace; sql / run
- Effect annotation: Read-only
| Input | Requirement | Description |
|---|---|---|
key | Required | The opaque base64 key id returned by the key scan. |
id | Required | string |