source_create
Validate adapter configuration and persist a source endpoint for the authenticated workspace.
When to use it
Use source_create to configure a source. This tool operates at workspace scope. It does not require a project context unless a filtering argument explicitly asks for one.
Plugin requirements
Connector dependency depends on the endpoint. These tools manage endpoint configuration, policies or grants; they do not install a connector or add capabilities to it. A plugin-backed endpoint must reference a configured connector installation. Use the plugin setup guides for configuration. Inspect the workspace’s plugin installations and check the installation before executing it.
Arguments
| Name | Type | Required | Default | Constraints |
|---|---|---|---|---|
name | string | Yes | — | Minimum length: 1; Maximum length: 160; Pattern constraint; see full schema |
namespace | string | Yes | — | Minimum length: 1; Maximum length: 100; Pattern constraint; see full schema |
role | string | No | "source" | Allowed: "source", "destination", "ontology_store", "event_source", "event_sink", "api", "file_store", "search_index", "graph_store", "other" |
pluginCapabilityInstallationId | union | No | — | Alternative shapes; see full schema |
contractKind | string | No | "source_stream" | Allowed: "source_stream", "source_query", "read", "write", "call_api", "subscribe_events", "publish_events", "ontology_fact_store", "transactional_table" |
target | object | Yes | — | See the full input schema |
schemaHints | object | No | {"primaryKey":[],"columns":[]} | Fields: primaryKey, columns |
freshness | union | No | — | Alternative shapes; see full schema |
ownerTeam | union | No | — | Alternative shapes; see full schema |
trustRank | string | No | "medium" | Allowed: "low", "medium", "high" |
description | string | No | "" | Maximum length: 1000 |
accepts | union | No | — | Alternative shapes; see full schema |
emits | string | No | "parquet" | Minimum length: 1; Maximum length: 100 |
idempotencyKey | string | Yes | — | Minimum length: 8; Maximum length: 200 |
View the complete input schema, including nested contracts and alternative shapes. The schema is extracted from the workspace server’s Zod definitions. Runtime validation also enforces custom checks that JSON Schema cannot express.
Response shape
The implementation constructs payloads using these fields: source. The returned fields depend on the execution path.
MCP returns a text block containing the JSON operation result and a
structuredContent copy. The envelope includes data, completeness,
truncated, freshness, and warnings. Depending on the operation it can also
include nextCursor, evidence, job, or receipt.
Check those fields before treating a conversational summary as the result.
When a job is returned, inspect its status with the appropriate execution tool;
a queued response is not confirmation that work finished. Follow evidence links
when checking the underlying records.
Input methods
This request illustrates the argument structure. Replace every angle-bracket placeholder with a real value and supply any applicable optional fields from the schema. Nested business contracts must match your actual configuration. Send it through an authenticated, initialized MCP client; this JSON alone does not establish a session or sign you in.
Open workspace Data Endpoints → New data endpoint and choose Edit manually. Fill Name, Namespace, Direction and Capability. For a readable capability exposing both contracts, choose Stream or Query in Source contract. Fill the target’s labeled fields, review and save. Use the values from this example’s argument table; UUIDs select real workspace resources rather than text to paste into labels.
Use Semogram’s source_create tool to configure a source. Inspect the required inputs and target first, then show me what will change before executing it.
Use real resource IDs returned by earlier reads; a resource name is not a UUID. Do not fill missing business inputs with invented values.
Use a workspace API key with endpoints:write. Set SEMOGRAM_API_KEY in your shell; replace resource placeholders with real IDs. This is an HTTP resource request, not an MCP JSON-RPC message.
curl --request POST "https://platform.semogram.com/api/v1/data-endpoints" \
--header "Authorization: Bearer ${SEMOGRAM_API_KEY}" \
--header "Idempotency-Key: <UNIQUE_KEY_FOR_THIS_OPERATION>" \
--header "Content-Type: application/json" \
--data-binary @- <<'JSON'
{
"name": "<NAME>",
"namespace": "<NAMESPACE>",
"target": {}
}
JSONThis is an MCP tools/call request, not a form to paste into Semogram. Send it through an authenticated, initialized MCP client.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "source_create",
"arguments": {
"name": "<NAME>",
"namespace": "<NAMESPACE>",
"target": {},
"idempotencyKey": "<UNIQUE_KEY_FOR_THIS_OPERATION>"
}
}
}FAQ
What access and approvals are required?
Required permission scopes: endpoints:write.
OAuth uses current workspace membership; API keys use their assigned scopes
and grants. Discovery can exclude tools the caller cannot use.
Read-only annotation: No. Destructive annotation: No. Follow the operation’s declared contract and any applicable server-side approval policy.
How should I handle retries?
The server marks this operation as idempotent. When an idempotencyKey is accepted, keep the same key only for a retry of the exact same input; use a new key for new work. For 429 responses, honor Retry-After rather than retrying immediately.
Why is this tool missing or returning an error?
Confirm the workspace, resource IDs, and permission scopes. Read the returned error before changing the request. See connection, authentication and troubleshooting for sign-in, scope, resource access, and rate-limit errors.