MCP tools catalogue

Expecto exposes its full functionality as an MCP server, so an AI assistant (Claude Desktop, Claude Code, Cursor, or an in-house client) can drive the platform directly: onboard suppliers, build contracts and transformers, run sessions, and inspect results. This page lists every available tool, grouped by domain.

For connection and authentication, see the Developer Quickstart → "Do the same thing through MCP". In short: point your client at <EXPECTO_BASE_URL>/mcp/ and authenticate with the same X-API-Key header used for the REST API.

Reading the catalogue

Descriptions below are one-liners. Your MCP client exposes each tool's full input schema (parameter names, types, which are required) via introspection — most clients show this when you inspect or call a tool. The parameters in parentheses are the inputs each tool accepts; required ones depend on the tool. The equivalent REST surface is documented interactively at <EXPECTO_BASE_URL>/api/docs.

All tools are scoped to the organization behind your API key. Tools that mutate state (create_*, update_*, delete_*, run_*, approve_*, …) require the corresponding permission on the key.

Identity & health

Tool	Purpose
get_identity	Return the principal, organization, and effective permissions behind the API key.
health	Check MCP server status and version.

Projects

Tool	Purpose
list_projects	List projects in the organization (optional search).
get_project	Full project detail: entities, catalogs, data contracts, receivers, and context_schema (required session-context scalars/tables to set before running a pipeline).
get_project_instructions	Read a project's operational instructions (markdown).
create_project	Create a project (delivery standard); optionally set the export output_format.
update_project	Update project settings (approval mode, session-creation mode, blocking severity, export output_format).
set_project_context_schema	Replace the project's session-context schema (scalars + tables, each with required / filled_by). Read the current one via get_project, merge, and pass the whole result; mark integration-filled fields filled_by: "integration".
update_project_instructions	Replace a project's operational instructions.
delete_project	Delete a project and all its scoped resources.
attach_entity_to_project	Attach an existing entity to a project under a semantic role.
detach_entity_from_project	Detach an entity from a project by its role name.
attach_catalog_to_project	Attach an org-level catalog to a project.
detach_catalog_from_project	Detach an org-level catalog from a project.

Entities

Target schemas plus row-level validation rules.

Tool	Purpose
list_entities	List entities (target schemas) in the organization.
get_entity	Entity detail including schema and validation rules.
create_entity	Create a new entity (org-level or project-scoped).
update_entity	Update an entity's name or description.
delete_entity	Delete an entity and its schema/rules.
set_entity_schema	Create or replace the JSON Schema for an entity.
get_entity_schema	Get the JSON Schema definition for an entity.
create_entity_rule	Create a validation rule on an entity. message accepts a string or a multilingual object ({"en": …, "de": …, "ru": …}, "en" required).
update_entity_rule	Update an existing validation rule. message accepts a string or a multilingual object.
delete_entity_rule	Delete a validation rule from an entity.

Data contracts

Supplier format agreements and their immutable revisions.

Tool	Purpose
list_data_contracts	List data contracts (supplier format agreements).
get_data_contract	Contract detail including revisions and sources.
create_data_contract	Create a new data contract (optionally with a caller-owned external_id, unique per organization).
add_source_to_contract	Add a source (role + type + parsing config) to a revision.
create_revision	Create a new draft revision on an existing contract.
activate_revision	Activate a draft revision (with a valid_from period).
update_data_contract	Update a contract's name, description or external_id (pass an empty string to clear it; the value is usable in v1 session creation as data_contract: {"external_id": …}).
delete_data_contract	Delete a contract and all its revisions/sources.

Transformers

Field mappings from a contract's sources to an entity's target schema.

Tool	Purpose
list_transformers	List transformers for a data contract.
get_transformer	A transformer with its full field mappings.
create_transformer	Create a transformer (mappings from contract to entity; optional per-role row filters).
update_transformer_mappings	Replace a transformer's field mappings, and optionally its row filters.
validate_transformer_expressions	Validate all mapping expressions (and row filters) in a transformer.
preview_transformer_sql	Preview the compiled DuckDB SQL for a transformer.
delete_transformer	Delete a transformer from a data contract.

Row filters (row_filters_json). create_transformer and update_transformer_mappings accept an optional row_filters_json map of {role: predicate}. Each predicate is a boolean DuckDB SQL expression; input rows where it evaluates false are dropped before mapping, so they never reach the entity data, validation, reconciliation, or the export package. Use it to exclude explicit-not-mapped accounts from the SAP output, e.g. {"postings": "\"Konto\" NOT IN (SELECT \"code\" FROM cat_kontenplan__provider WHERE \"mapping_type\" = 'ignore')"}. On update, omitting row_filters_json leaves existing filters unchanged; passing {} clears them. Dropped-row counts are reported in the session's transform summary.

Catalogs

Reference data sets (charts of accounts, code tables, exclusion lists). A catalog is scoped to the organization, a project, or — via data_provider_id — a single supplier.

Tool	Purpose
list_catalogs	List catalogs. Filter by project_id, or by data_provider_id for provider-scoped catalogs.
get_catalog_data	Read a catalog's columns and rows (paginated).
create_catalog	Create a catalog — org-level, project-scoped (project_id), or provider-scoped (data_provider_id).
update_catalog	Update a catalog's name or description.
delete_catalog	Delete a catalog and its data.
import_catalog_data	Import CSV/Excel into a catalog (replaces existing data).
add_catalog_column	Append a column (with a default) without re-importing — existing rows are preserved.
edit_catalog_cell	Set a single cell by row index, e.g. flag one account's mapping_type = 'ignore'.

Data providers

Suppliers that submit data. A provider gets access to a project, can have member user accounts, and can own provider-scoped catalogs.

Tool	Purpose
list_data_providers	List suppliers (data providers). Use the returned id as data_provider_id for provider-scoped catalogs.
get_data_provider	A single provider's details by id.
create_data_provider	Create a provider (name, optional external_id, language en/de/ru).
update_data_provider	Rename, change external_id, set message language (en/de/ru), or set is_active.
deactivate_data_provider	Deactivate a provider (soft delete — is_active = false).
list_provider_members	List the user accounts attached to a provider.
add_provider_member	Attach a user by user_id or email with a role (contributor / manager); an unknown email is auto-provisioned into the org.
remove_provider_member	Detach a member (by membership id).
list_provider_access	List a provider's project access grants.
grant_provider_access	Grant access to a project_id (optionally scoped to a data_contract_id).
revoke_provider_access	Revoke an access grant (by grant id).

Integrations, context sources & outbound bindings

Connections to external systems and the per-project configuration around them. A connection's adapter declares capabilities: context (auto-fill session context — BuiltAPI, PostgreSQL) and/or outbound (write session events to the external platform — Salesforce). Context sources let the caller send only query parameters (e.g. period, fund number) while Expecto fetches the rest at session creation; outbound bindings push check results out when a run completes.

Tool	Purpose
list_connection_types	Catalog of supported connection types: each entry carries the type's capabilities (context / outbound) and the form metadata to collect a connection of that type — base_url shape, credential shape (single token or structured fields), and config fields with required flags. Call it before create_integration_connection.
create_integration_connection	Create an org-scoped connection (name, type = builtapi, postgres, or salesforce, base_url — an API URL, a postgresql:// DSN, or a Salesforce My Domain instance URL, config_json — workspace_id for BuiltAPI, api_version for Salesforce, write-only credentials — a token string, or {client_id, client_secret} for OAuth types).
list_integration_connections	List connections; responses expose capabilities (context / outbound) and has_credentials, never the secret.
update_integration_connection	Rename, change config, rotate (credentials) or clear (clear_credentials) the token, toggle is_active.
test_integration_connection	Probe a saved connection (connection_id, stored credentials) or an unsaved payload with a cheap authenticated call; returns {ok, error_kind, message}.
delete_integration_connection	Delete a connection; rejected while any project's context sources or outbound bindings reference it.
set_project_context_sources	Declare what to fetch: sources with a BuiltAPI query — records_search (filter + projection) or aggregation (Mongo pipeline with $lookup) — or a PostgreSQL sql query (single read-only SELECT); {{ context.* }} / {{ session.* }} placeholders — and the context table/scalar each one produces. BuiltAPI queries are paginated automatically and fetch all rows; the optional take is a total row limit (1–100 000), not a page size. Without take, a result exceeding 100 000 rows fails with an explicit error instead of being truncated silently.
get_project_context_sources	Read the project's context-sources configuration.
test_context_source	Dry-run one source's query with sample placeholder values; returns a preview (row count, columns, first rows) or a semantic error, without creating a session.
fetch_session_context	Re-run the automatic context fetch for a session (allowed until it is confirmed); outcome lands in context_fetch_report.
set_project_outbound_bindings	Declare which session events are written where: bindings with an outbound-capable connection, events (e.g. session.checked, session.failed) and an adapter-specific mapping — for Salesforce: sobject + fields with {{ … }} templates over envelope fields (session_id, run_id, health, …) and {{ context.* }}.
get_project_outbound_bindings	Read the project's outbound bindings.

Mark integration-filled fields with filled_by: "integration" in the project context schema so callers are not asked to provide them; a pending or failed fetch blocks the pipeline before parse with per-source, human-readable reasons.

Per-platform guides (Salesforce-side setup, query kinds, limits, error semantics) are in the Integrations section.

Webhooks

Outbound webhooks for session lifecycle events (Standard Webhooks-compliant). Endpoints are org- or project-scoped; signing secrets are shown once and Fernet-encrypted at rest.

Tool	Purpose
list_webhook_endpoints	List the organization's webhook endpoints.
get_webhook_endpoint	A single endpoint's details by id.
create_webhook_endpoint	Create an endpoint (url, event_types, optional project_id, optional auth header). Secret returned only with reveal_secret=true.
update_webhook_endpoint	Update URL, event types, active state, or auth header.
delete_webhook_endpoint	Delete an endpoint and its deliveries.
rotate_webhook_secret	Rotate the signing secret (shown once with reveal_secret=true).
send_webhook_ping	Send a synthetic webhook.ping to verify connectivity.
list_webhook_deliveries	List delivery attempts — for one endpoint, one connection (connection_id), or the whole organization; outbound-binding deliveries carry connection_id / project_id / binding_name, and a successful one stores the upstream record reference.
get_webhook_delivery	A single delivery's details, including the last response excerpt.
replay_webhook_delivery	Re-send a past delivery — endpoint deliveries with the original signed body, outbound-binding deliveries through the adapter.

Business rules

Cross-entity reconciliation and project-level checks (DuckDB SQL / expression).

Tool	Purpose
list_business_rules	List business rules for a project.
get_business_rule	A specific business rule with full details.
create_business_rule	Create a business rule (optionally gated by applicable_when_sources). message accepts a string or a multilingual object ({"en": …, "de": …, "ru": …}, "en" required).
update_business_rule	Update a business rule. message accepts a string or a multilingual object.
delete_business_rule	Delete a business rule from a project.

Sessions

One delivery act: files → parse → transform → validate → check → confirm → approve → export.

Tool	Purpose
list_sessions	List sessions (filter by project, status, health, search).
get_session	Session detail: files (with per-file parse_validation_summary), transformers, pipeline status, plus context_validation_errors and file_validation_errors.
create_session	Create a delivery session for a contract + period (+ provider).
upload_session_file	Upload a file against a source role.
run_session_pipeline	Run the full pipeline (parse → transform → validate → check); returns job_id (polling handle) and run_id — the stable ID of the minted run (one per execution, see GET /sessions/{id}/runs). A failed pre-flight gate returns error + details naming the missing context fields or source files. A blocked session can be re-run (each call mints a new run; health stays blocked until the re-run passes). If the automatic context fetch is still pending, parse runs right away (the technical result does not wait for the context) and the run then waits before transform — get_job_status shows run_status = waiting, waiting_for = context_fetch — and continues by itself when the fetch completes (same run_id / job_id); a failed fetch or a wait past the timeout closes it as errors.
set_session_context	Set session context values (scalars and tables).
get_session_parse_issues	Parse validation issues for one uploaded file: summary counts, groups by (check, column) with counts, format hints and sample rows, plus a paginated raw issues list. The only way to read the full parse errors — get_session carries just the summary.
get_session_violations	Validation violations for a session transformer.
get_session_check_violations	Business-rule check violations for a specific rule.
confirm_session	Confirm a checked session (reviewed by the submitter).
approve_session	Approve a confirmed session (final sign-off before export).
reject_session	Reject a confirmed session and send it back for corrections.
export_session	Export a session's output package as a trackable job; the project must have an output format configured.
add_session_comment	Add a comment to a session.
list_session_comments	List a session's comments in chronological order.

Jobs

Asynchronous work (pipeline runs, exports, imports) is tracked as jobs.

Tool	Purpose
get_job_status	Status of an async job (pipeline run, export, import). For a pipeline job also run_id, run_status and waiting_for (context_fetch while the run waits for the context fetch).
list_jobs	Recent async jobs for the organization.