Search documentation

Search for a topic, a control, or an event type.

    Docs / Workflows / Integrations / Custom integrations

    Custom integrations

    Connect your own HTTPS API or an MCP server, define the actions OAIZ can run against it and receive events from your own systems.

    A custom integration connects a service that has no built-in OAIZ integration. Its Source type is either HTTP API, for a REST-style API reached over HTTPS, or MCP server, for a remote Model Context Protocol server. Choose Custom in the New integration dialog to create one.

    The connection holds the address and the credentials. Its actions describe the operations OAIZ can run, and jobs, Agent tools and Code use them like any other integration action. Each custom integration also gets its own service account, which your systems use to send events into it.

    Name and provider identifier

    Name
    The label shown in Integrations and in job settings, up to 255 characters. No two active integrations in an organisation share a name.
    Provider
    An identifier in the form custom-<slug>, such as custom-acme-crm, using lowercase letters, digits and hyphens. Actions and event types use it. It cannot change while the integration exists and becomes free again after the integration is deleted.
    Icon
    A colour icon, an icon discovered from the service, or an uploaded PNG, JPEG, WebP or ICO image up to 1 MiB.

    The Access step sets who else can use the connection when it is created. A custom integration starts private to the person who creates it, who becomes its Owner.

    HTTP API connection

    An HTTP API connection starts with a Base URL, an absolute HTTPS address without embedded credentials, such as https://api.acme.example. Every action path is joined to it. Authentication is set afterwards in Custom integration settings on the integration’s page and applies to every action.

    None
    Requests carry no credential.
    Bearer token
    Sends Authorization: Bearer with the saved token.
    API key
    Sends the saved key in the header named in API key header.
    Basic auth
    Sends the saved username and password.
    Session login
    Logs in to the site with a username and password and reuses the session cookies for later requests.

    Saved secrets are never shown again. A field reports that a credential is configured, and entering a value replaces it. Fixed headers adds up to 64 visible headers to every request, so they must not hold secrets. Sign request bodies adds a header, Oaiz-Webhook-Signature by default, containing the lowercase hex HMAC-SHA256 of the exact request body, computed with your signing secret.

    OAIZ sends each request once and does not follow redirects. A request times out after 30 seconds, and a response body can be at most 10 MiB.

    Session login

    Session login suits a site that accepts a form or JSON login instead of an API credential. The Login flow describes the Login request, with its Login path, Body format, Username field and Password field. It can first open a Login page to receive a cookie or read a CSRF token from an HTML input, an HTML meta tag or a JSON response field.

    The Login success check recognises a successful login by a redirect or by a JSON field that is true, optionally with text the logged-in page must contain. Session expiry tells OAIZ how an action response shows that the session ended: an HTTP status, a redirect to the login page or a marker in the page. At least one is required.

    Everyone with access to the connection can see the login settings, while the password stays write-only. Saving does not log in. The next action run or Try does. When a login fails, the integration shows Log in again, and workflows and agents do not use the connection until the login works. Logins that need a CAPTCHA, multi-factor authentication or a browser check are not supported.

    HTTP actions

    An HTTP action defines one request. Create action opens the editor. Its settings are visible to the connection’s Owners and never contain the connection’s credentials.

    Action key
    A permanent lower snake case identifier of up to 64 characters, such as get_widget.
    Action name and Description
    How the action appears in job settings and to agents choosing a tool.
    HTTP method
    GET, HEAD, POST, PUT, PATCH or DELETE.
    Relative path
    A path beginning with /, with named placeholders such as /widgets/{widgetId}. Path bindings map each placeholder to a required input property.
    Query bindings
    Map query parameter names to top-level input properties.
    Action headers
    Visible, non-secret headers for this action only. Connection authentication is added separately.
    JSON body template
    An optional JSON object that takes values from the action’s inputs. GET and HEAD cannot send a body.
    Input schema
    A JSON Schema object describing the inputs the action accepts. Top-level property names start with a letter or _ and use only letters, digits and _, up to 64 characters.
    Output schema
    An optional JSON Schema describing the response. Later jobs use it to find the action’s output fields.
    JSON body template
    {
      "id": "{{ arguments.widgetId }}",
      "active": "{{ arguments.active }}"
    }

    The Safety classification sets Read or write, a destructive flag for writes that can delete or overwrite data, and Enabled. The method suggests values until you change them. Review save shows the exact method and classification for confirmation before the action is saved.

    Read or write decides whether the action counts as a read tool or a write tool for sharing, and whether a test run performs it. A test run that does not perform a write returns example values built from the output schema. A disabled action cannot run in workflows or agents. Deleting an action pauses the live workflows that use it until you repair and resume them.

    In a run, any status outside 200 to 299 fails the action. A JSON object response becomes the action’s output fields. Any other JSON value or a text response is returned in body.

    Try an action

    Try sends one real request or tool call through the saved connection, so a write action changes the external service. The dialog shows the saved classification, takes values for the declared inputs and shows the response status, headers and body. Try stays available for a disabled action so it can be repaired.

    For a JSON response from an HTTP action, Try also offers an Inferred output schema draft. Save inferred schema writes that draft to the action after a confirmation. The response itself is never saved. An MCP action that can change remote data asks for Confirm and run before the call.

    MCP server connection

    An MCP server connection uses the MCP endpoint, an HTTPS address such as https://mcp.example.com/mcp. The server must offer Streamable HTTP with MCP version 2025-03-26, 2025-06-18, 2025-11-25 or 2026-07-28. OAIZ does not follow redirects, so enter the final endpoint address. When you enter the endpoint, OAIZ reads the server’s name and whether it requires OAuth, and fills in Name and Server authentication unless you have changed them.

    No authentication
    Calls carry no credential.
    API key
    Sends the saved key in the API key header, Authorization by default. Headers that MCP reserves cannot be used.
    OAuth
    Connect with OAuth opens the server’s sign-in in a pop-up window. The server’s authorization server must allow dynamic client registration. Reconnect with OAuth in the settings renews the connection.

    What this server publishes shows what the server advertised at the last discovery: its version, website, instructions, prompts, resources and resource templates. Prompts are listed for reference and are not imported.

    MCP actions and rediscovery

    Creating an MCP integration discovers the server’s tools, text resources and URI templates and saves each compatible one as an action. The server owns each action’s name, description and input and output schemas. View action specification shows them. Unsupported server actions lists any that failed to import, with the reason.

    A tool’s Read or write class starts from the server’s read-only and destructive hints. Without hints, a tool whose name starts with a lookup word such as get, list or search, and names no change, is Read. Every other tool is Write and is flagged as destructive unless the server says otherwise. Edit action settings changes Access, the destructive flag and Enabled.

    Rediscover actions reads the server again and reports how many actions it added, updated, marked unavailable or found unsupported. Your Enabled settings and any classification you changed stay. Before each call OAIZ checks the tool’s current definition. A tool that changed or disappeared fails until the next rediscovery. An action whose tool or resource is gone becomes unavailable, and the live workflows that use it are paused.

    A tool’s structured result becomes the action’s output, checked against its output schema. A single text reply is returned as text, and several text blocks are returned in body with each block listed in content. Image, audio and binary content are not supported. When a tool reports an error, OAIZ fails the call without showing the server’s error text.

    Events from your systems

    A custom integration receives events your systems publish. Send them to the event publish endpoint with an API key from the integration’s Incoming API keys, and set the event type’s provider to the integration’s Provider identifier. For example, provider custom-acme-crm and name order-created make the event type e:custom-acme-crm/order-created, which a workflow can listen for.

    Only that integration’s service account can publish events with its provider identifier. Other credentials are refused. The events belong to the connection, so everyone with a grant on it can read them. Event types are not declared in advance. Received events lists each type once the first delivery arrives, with its Deliveries, First received and Last received. Properties schema keeps the schema of the first delivery, and later deliveries do not replace it.

    Service account and Incoming API keys

    Creating a custom integration also creates a service account that belongs to it and is managed by its creator. Incoming API keys creates and revokes that account’s keys. Each key authenticates as the account with its ordinary permissions, so it is not limited to publishing events. Grant the account only the access your system needs.

    Skill

    The Skill is guidance OAIZ’s agents follow when they use the integration’s tools, such as which identifiers an action expects or which call to make first. Agents read it when they build workflows and jobs that use the integration. An Agent job with tools from the integration receives it with its instructions on every run, so a saved change applies from the next run.

    An MCP integration follows the server’s instructions until an Owner edits the skill text. Reset to server instructions removes the edit. An HTTP integration has no skill until one is written. The skill text can be up to 4,500 bytes, and saving it empty turns guidance off.

    Access and use

    A custom integration uses the same View, Edit and Owner roles and tool restrictions as any other connection. Only Owners see and change Custom integration settings, the Skill and the action list, and only they can Try an action. Used by lists the live workflows and jobs that use the integration.

    An enabled action is available as a standalone integration job, an Agent tool and a Code SDK call.