> ## Documentation Index
> Fetch the complete documentation index at: https://hadiqio.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Actions

> Give Hadiq.io AI Agents the ability to call external APIs and tools by connecting OpenAPI specs or MCP servers.

Actions extend what Hadiq.io AI Agents can do. Without actions, an Agent can search knowledge and generate text. With actions, it can also interact with external systems — creating Jira tickets, querying a database, triggering a workflow, or calling any REST endpoint.

There are two types of actions:

* **OpenAPI actions** — Upload an OpenAPI spec to let agents call the REST endpoints defined in it.
* **MCP actions** — Connect an external MCP server so agents can use its tools.

Manage both types under **Admin → Actions**.

<Note>
  Actions must be explicitly enabled on each Agent that should use them. Adding an action in Admin makes it available, but you still need to assign it to the Agent in **Admin → Agents** (or **App → Agents → Edit**).
</Note>

## OpenAPI actions

OpenAPI actions let you give agents access to any REST API by uploading its OpenAPI specification. Hadiq.io parses the spec and exposes each endpoint as a tool the agent can call.

<Tabs>
  <Tab title="Adding an OpenAPI action">
    <Steps>
      <Step title="Open the OpenAPI actions page">
        Go to **Admin → Actions → OpenAPI**. Click **Add Action**.
      </Step>

      <Step title="Paste your OpenAPI schema">
        In the **OpenAPI Schema Definition** field, paste the full JSON (or JSON with trailing commas) of your OpenAPI spec.

        Hadiq.io validates the schema in real time and shows a preview of the endpoints it will expose as tools. The action name and description are derived from the spec's `info.title` and `info.description` fields.

        <Tip>
          Use the format button in the editor to auto-format your JSON before saving.
        </Tip>
      </Step>

      <Step title="Review the extracted tools">
        After pasting a valid schema, Hadiq.io displays the list of endpoints (tools) it detected, including the HTTP method, path, and summary for each. Confirm the list looks correct.
      </Step>

      <Step title="Save the action">
        Click **Add Action**. The action is saved and appears in your OpenAPI actions list.
      </Step>

      <Step title="Configure authentication">
        Most external APIs require authentication. After saving, click the action to open it and then click **Edit Configs** to set up authentication.

        See [Authentication options](#authentication-options) below for the available methods.
      </Step>

      <Step title="Assign to an Agent">
        Go to **Admin → Agents** (or open an Agent in the app), edit the Agent, and enable the action you just created. The Agent can now call the action's endpoints during a conversation.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Authentication options">
    Hadiq.io supports three authentication methods for OpenAPI actions:

    **OAuth**

    Each user authenticates independently using OAuth. Hadiq.io handles the OAuth flow and stores tokens per user.

    Required fields:

    * Authorization URL
    * Token URL
    * Client ID
    * Client Secret
    * Scopes (optional, comma-separated)

    Use the redirect URI shown in the modal when registering Hadiq.io with the OAuth provider.

    **OAuth pass-through**

    Hadiq.io forwards the user's existing Hadiq.io OAuth access token directly to the external API. Use this when the external service shares the same identity provider as your Hadiq.io instance (requires Hadiq.io to be configured with OIDC or Google OAuth).

    **Custom authorization header**

    Send one or more static HTTP headers with every request. This is the standard method for API key authentication:

    ```
    Authorization: Bearer <your-api-key>
    ```

    You can add multiple headers if the API requires additional values (e.g. `X-Tenant-ID`).
  </Tab>

  <Tab title="Example: GitHub API">
    Here is a minimal OpenAPI spec for a GitHub action that lets agents list issues:

    ```json openapi-github-example.json theme={null}
    {
      "openapi": "3.1.0",
      "info": {
        "title": "GitHub Issues",
        "description": "List and read GitHub issues",
        "version": "1.0.0"
      },
      "servers": [
        { "url": "https://api.github.com" }
      ],
      "paths": {
        "/repos/{owner}/{repo}/issues": {
          "get": {
            "operationId": "listIssues",
            "summary": "List repository issues",
            "parameters": [
              { "name": "owner", "in": "path", "required": true, "schema": { "type": "string" } },
              { "name": "repo", "in": "path", "required": true, "schema": { "type": "string" } },
              { "name": "state", "in": "query", "schema": { "type": "string", "enum": ["open", "closed", "all"] } }
            ],
            "responses": {
              "200": { "description": "A list of issues" }
            }
          }
        }
      }
    }
    ```

    After uploading this spec, configure **Custom Authorization Header** authentication with:

    ```
    Authorization: Bearer ghp_your_github_token
    ```
  </Tab>
</Tabs>

## MCP actions

MCP actions connect Hadiq.io agents to external MCP servers. Any MCP server your organization runs or subscribes to can be added here, giving agents access to all of that server's tools.

<Tabs>
  <Tab title="Adding an MCP action">
    <Steps>
      <Step title="Open the MCP actions page">
        Go to **Admin → Actions → MCP**. This is the default view when you navigate to Admin → Actions.
      </Step>

      <Step title="Add a new MCP server">
        Click **Add MCP Server** and fill in:

        * **Server Name** — a label for this connection (e.g. "Jira MCP", "Salesforce MCP")
        * **Description** — optional, helps distinguish servers with similar names
        * **MCP Server URL** — the HTTP endpoint of the external MCP server (e.g. `https://your-mcp-server.com/mcp`)

        Click **Add Server**.

        <Warning>
          Only connect to MCP servers you control or trust. Agents can execute any tool exposed by the server on behalf of your users.
        </Warning>
      </Step>

      <Step title="Authenticate the connection">
        After saving, Hadiq.io prompts you to authenticate the connection. Select an authentication method and fill in the required credentials.

        See [Authentication options](#mcp-authentication-options) below for the available methods.

        Click **Connect** to complete the setup.
      </Step>

      <Step title="Verify tools are loaded">
        After authenticating, Hadiq.io fetches the available tools from the MCP server. The server card expands to show the list of tools it exposes. If no tools appear, check that the server URL is correct and the authentication is valid.
      </Step>

      <Step title="Assign to an Agent">
        Go to **Admin → Agents** (or open an Agent in the app), edit the Agent, and enable the MCP server. The Agent can now call any of the server's tools during a conversation.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Authentication options" id="mcp-authentication-options">
    Hadiq.io supports four authentication methods for MCP servers:

    **OAuth**

    Each user authenticates independently using OAuth. Hadiq.io handles the OAuth flow per user. Optionally provide a Client ID and Client Secret if the server does not support Dynamic Client Registration (DCR).

    Use the redirect URI shown in the modal when registering Hadiq.io with the OAuth provider.

    **OAuth pass-through**

    Hadiq.io forwards the user's existing Hadiq.io OAuth access token to the MCP server. Use this when the server and Hadiq.io share the same identity provider.

    **API Key**

    Two sub-modes are available:

    * **Individual key (per user)** — Each user provides their own API key, which Hadiq.io stores separately per user. Use this when the external service has per-user API keys.
    * **Shared key (admin)** — An admin provides a single organization-wide API key. All users share this key when the agent calls the MCP server.

    <Warning>
      When using a shared admin API key, choose a service account key rather than a personal API key. Actions taken with this key are visible to anyone using the Agent.
    </Warning>

    **None**

    No authentication. Only use this for MCP servers on a trusted internal network that do not require credentials.
  </Tab>
</Tabs>

## Assigning actions to agents

Adding an action in Admin makes it available to all agents, but it is not active until you assign it to a specific agent.

To assign an action:

1. Go to **Admin → Agents** or open **App → Agents**.
2. Select the agent you want to edit.
3. In the agent's configuration, find the **Actions** section.
4. Enable the OpenAPI actions or MCP servers you want this agent to use.
5. Save the agent.

<Tip>
  Assign only the actions relevant to each agent's purpose. An agent with fewer, more targeted actions is easier for the LLM to use correctly than one with dozens of unrelated tools.
</Tip>

## Managing existing actions

**OpenAPI actions** — Go to **Admin → Actions → OpenAPI** to view all actions. Click an action to edit its schema or update its authentication configuration.

**MCP servers** — Go to **Admin → Actions → MCP** to view all connected servers. Each card shows the server's connection status and the tools it exposes. Click **Manage** to update the server URL, re-authenticate, or disconnect.

To remove an action or server, disconnect it from its management page. This also removes it from any agents it was assigned to.