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.

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).

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.

Adding an OpenAPI action

1. Open the OpenAPI actions page

   Go to Admin → Actions → OpenAPI. Click Add Action.

2. 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.

   Use the format button in the editor to auto-format your JSON before saving.

3. 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.

4. Save the action

   Click Add Action. The action is saved and appears in your OpenAPI actions list.

5. 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 below for the available methods.

6. 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.

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).

Example: GitHub API

Here is a minimal OpenAPI spec for a GitHub action that lets agents list issues:

openapi-github-example.json

{
  "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

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.

Adding an MCP action

1. Open the MCP actions page

   Go to Admin → Actions → MCP. This is the default view when you navigate to Admin → Actions.

2. 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.

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

3. 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 below for the available methods.

   Click Connect to complete the setup.

4. 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.

5. 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.

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.

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.

None

No authentication. Only use this for MCP servers on a trusted internal network that do not require credentials.

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.

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.

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.