MCP tools

The server name is dataporch. Direct HTTP clients use stateless Streamable HTTP with JSON responses at /mcp; requests are limited to 1 MiB. Bundled plugins use dataporch mcp over stdio, which forwards the same tool contract through the owner-only local Unix socket. Every discovery tool is read-only, idempotent, non-destructive, and closed-world. Query is read-only and non-idempotent in its annotation because the server cannot assume a caller-supplied statement is repeat-safe.

data_source.list

List configured sources without connecting to them.

{
  "search": "finance",
  "limit": 20,
  "cursor": "opaque-value"
}

All fields are optional. The result contains sources, each with id, kind, and capabilities, plus an optional next_cursor.

relational_database.list_schemas

{
  "source_id": "finance",
  "include_descriptions": true,
  "limit": 50
}

search, limit, and cursor are optional. Use the returned schema name exactly in the next call.

relational_database.list_tables

{
  "source_id": "finance",
  "schema": "public",
  "search": "invoice",
  "include_descriptions": true,
  "limit": 50
}

The adapter may return tables, partitioned tables, views, materialized views, foreign tables, or SQLite virtual tables according to the source.

relational_database.list_columns

{
  "source_id": "finance",
  "schema": "public",
  "table": "invoices",
  "include_descriptions": true
}

Column output includes names, ordinal positions, formatted and database types, nullability, defaults, identity/generated metadata, descriptions, and relevant constraints where the adapter exposes them.

relational_database.query

The input is exactly three fields:

{
  "kind": "postgres",
  "source_id": "finance",
  "query": "SELECT invoice_id, total FROM public.invoices WHERE status = 'open' LIMIT 25"
}

query must be one complete row-producing statement. kind must match the configured source (postgres, sqlite, or mysql). The result shape is:

{
  "kind": "postgres",
  "source_id": "finance",
  "columns": [{"name": "invoice_id", "database_type": "bigint"}],
  "rows": [["42"]],
  "row_count": 1,
  "truncated": false
}

Rows are arrays aligned with columns; null cells are JSON null. The server enforces the configured timeout, row limit, and encoded response-byte limit. A result with truncated: true is not complete.

Pagination

Pass next_cursor unchanged as cursor in the same operation with the same parent identifiers and search parameters. Cursors are opaque and request-bound. An invalid_cursor failure means restart that discovery operation from the first page.

Authentication

Direct HTTP clients send the long-lived local token as a bearer credential:

Authorization: Bearer dp-...

Do not use the MCP endpoint for source import or token lifecycle; those operations belong to the local admin socket and CLI.

The dataporch mcp stdio adapter reads the owner-only runtime credential from DATAPORCH_MCP_CONTROL_TOKEN_PATH and injects it into its local socket requests. Local plugin users do not create or export a bearer token. See Run locally for the socket and control-token paths.