Enrich with MCP

An MCP tool node calls one installed remote server tool for each incoming record and adds the result as a column. This example looks up region-owner information for two orders. It uses Postgres read and a workspace MCP server installation; connecting an external assistant to Semogram is a different direction of integration.

What you need

You need a Semogram account with workspace membership, a project in that workspace and permission to create and run pipelines. Reading or writing also requires access to the selected endpoints and external systems. Creating a pipeline does not grant those permissions.

Use a reachable test PostgreSQL database and its SQL client. You need installation/endpoint management access as well as pipeline read/write/execute access. The connection must be reachable from the execution runtime, not only from your laptop.

Prepare records

CREATE TABLE public.pipeline_demo_orders (
  order_id integer PRIMARY KEY,
  region text NOT NULL,
  total numeric(12,2) NOT NULL
);
INSERT INTO public.pipeline_demo_orders VALUES
  (1, 'North', 120.00),
  (2, 'South', 75.50);

Open workspace Plugins → Explore, find Postgres (@craven/postgres), inspect its installed contract and install the read capability. Fill these connection fields and run its supported connection check:

Open workspace Data Endpoints → New data endpoint. Use name demo_orders, namespace pipelines, direction Ingress, the installed Postgres read capability and Stream (source_stream) as the source contract. In the target fields set Schema to public and Table to pipeline_demo_orders. Save and inspect its schema/sample. demo_orders is a name you choose in Semogram; public.pipeline_demo_orders is the actual database table. Keep its returned endpoint UUID for programmatic examples.

The Postgres installation guide and endpoint guide provide additional detail; the required setup for this fixture is included here.

Prepare the remote service

You need a reachable remote MCP server that exposes an actual read-only region lookup. For this fixture, its illustrative tool get_region_owner accepts string argument region, returns North → Nora and South → Sam, and advertises readOnlyHint: true. This name is an example contract, not a built-in Semogram tool. Use a tool your server implements and adapt the argument name/result checks accordingly.

In workspace Plugins → MCP Servers, connect that server using its actual supported transport, URL and protected authentication settings. Discover its tools and inspect the lookup schema and read-only annotation. Test its two fixture calls before building the pipeline. Tools that change data, or do not affirm read-only behavior, are not allowed in this node.

Configure the graph

Create Ingress → MCP tool. Ingress reads demo_orders in Full load/parser mode into orders. Connect its output to the tool node input.

Read demo_orders and enrich each row using our installed remote region lookup server. Select its read-only get_region_owner tool, bind region from each row’s region field and save the result in region_lookup. Use two parallel calls. Show the discovered tool schema and bindings before saving.

{
  "capabilityRefId": "<MCP_SERVER_CAPABILITY_UUID>",
  "toolName": "get_region_owner",
  "input": "orders",
  "output": "enriched_orders",
  "arguments": {
    "region": {
      "field": "region"
    }
  },
  "resultField": "region_lookup",
  "concurrency": 2
}

Validate, save and run

Validate the draft and resolve errors. Preflight checks configuration only; it does not produce records or run a model. Save version, inspect the active saved graph and Run once. Open the run and compare the named step's output with the expected result below. Keep the run ID and inspect errors/counts, not only the assistant's response. Programmatic launch uses HTTP POST /api/v1/projects/<PROJECT_ID>/pipelines/<PIPELINE_ID>/execute with pipelines:execute and an Idempotency-Key, or MCP pipeline_execute with pipelineId, projectId and idempotencyKey.

If the Studio result only exposes an artifact handle, open the corresponding output/artifact inspection rather than treating that handle as a row preview. To persist rows externally, add an Egress endpoint and test its write semantics; the examples below do not silently create a destination.

Check behavior

Expect two output rows retaining order_id/region/total and a region_lookup result from the remote service on each. Inspect the result's actual object shape, not an assumed flattened owner column. Failed rows are retained with region_lookup_error; check completed/partial/failed status and failed count. The runtime supports remote http or sse, not stdio servers. Verify the North/South fixture responses, source lineage and remote call errors.

Parallel calls range from 1 to 8; configure within remote rate limits. Test missing arguments, no-match results and remote failures. Saving the server installation does not grant the service's account access or prove its token can perform the lookup.