Register an MCP tool source
Register a customer endpoint using inline write-only credentials or an authorized reference. No secret readback. Discovery is separate and does not execute a tool. conflict with details.reason=name_taken: the server name, or the secret name of an inline credential, is taken. resource_key_conflict: the resource_key of the server (create only) or of an inline credential is taken; details.resource_type says which. Inline credential material also requires secrets.manage, because it creates a secret; a {secret_id, version} reference also requires secrets.read.
Authentication
Create and manage workspace-owned keys through the existing app session routes, outside this public API. Creator and manager identities are audit actors only. Key validity follows workspace policy, expiry and explicit revocation, independently of creator membership. Do not include a workspace-selection header.
Headers
Stable key per logical intent, 1–255 printable characters. Persist it before sending. Retry the same key/body after an uncertain result for 24 hours. A changed body conflicts. Beyond retention, reconcile the resource before retrying; this is not permanent deduplication. Current authorization is rechecked on replay. Evaluation order: authenticate and check current authorization; look up intent; replay its stored receipt before checking the current revision; only a new intent evaluates If-Match and executes. Fingerprint includes method, path, body and original If-Match. A changed request returns idempotency_key_reused. The server stores only a keyed (HMAC) fingerprint, and no error or response ever returns a fingerprint or hash of a request. In-flight intent returns 409 idempotency_in_progress with Retry-After; retry the same intent after reconciliation. Receipts describe that attempt, not current resource state. A replay returns the original status code and body, with the response header Idempotent-Replayed: true.
Request
Exactly one of: an existing reference {secret_id, version} to an active version of a secret with the matching purpose, or new write-only inline material. No mixed shape. A reference to a revoked, deleted or wrong-purpose version refuses with credential_unavailable. References pin the exact version and never follow rotation.
Optional caller-chosen resource key: an opaque external identifier that matches your own record (for example a CRM ID, a configuration-file ID or a UUID) to this resource. Rasen still generates the canonical id; use id in paths and references. Case-sensitive, compared exactly, never normalized or parsed. 1-128 characters from A-Z a-z 0-9 . _ : ~ - and starting with a letter or digit; UUIDs and ULIDs are valid. Unique per resource type within one workspace; separate environment workspaces can reuse the same key. Set only at creation and immutable afterwards. A create with a key that already exists returns 409 resource_key_conflict with details.existing_id; it never updates or returns the existing resource. Not an Idempotency-Key: that header identifies one request intent for 24 hours, and a same-intent replay returns its original receipt before the resource-key check runs. Uniqueness includes archived resources. A key becomes free again only after its resource is permanently deleted or erased (a deleted secret or a deleted knowledge source); archive never frees it. On replaceMcpServer an omitted resource_key keeps the stored key, and a different value, including any value on a server that was created without a key, returns 409 conflict with details.reason=resource_key_immutable. Keys are set at create only.
Response headers
Strong mcp-server revision. Use this ETag for edits to this resource. Draft ETags cover complete authoring inputs.
true when this response replays a stored Idempotency-Key result. The status and body equal the original.
Response
Open response vocabulary. Preserve unknown values; never assume they mean success.
Open response vocabulary. Preserve unknown values; never assume they mean success.
Open response vocabulary. Preserve unknown values; never assume they mean success.
Exact pinned credential reference; null for auth=none. Never contains secret material.
Optional caller-chosen resource key: an opaque external identifier that matches your own record (for example a CRM ID, a configuration-file ID or a UUID) to this resource. Rasen still generates the canonical id; use id in paths and references. Case-sensitive, compared exactly, never normalized or parsed. 1-128 characters from A-Z a-z 0-9 . _ : ~ - and starting with a letter or digit; UUIDs and ULIDs are valid. Unique per resource type within one workspace; separate environment workspaces can reuse the same key. Set only at creation and immutable afterwards. A create with a key that already exists returns 409 resource_key_conflict with details.existing_id; it never updates or returns the existing resource. Not an Idempotency-Key: that header identifies one request intent for 24 hours, and a same-intent replay returns its original receipt before the resource-key check runs. Uniqueness includes archived resources. A key becomes free again only after its resource is permanently deleted or erased (a deleted secret or a deleted knowledge source); archive never frees it.