## Core concepts

Agen for SaaS provides the infrastructure for SaaS products to safely expose their APIs and capabilities to AI platforms and agents. It turns your product into an AI-native platform, allowing customers to interact with it through AI assistants like ChatGPT, Claude, Gemini, or custom MCP agents — while maintaining security, governance, and compliance.

This page explains the core concepts that make Agen for SaaS work.

### MCP Gateway

The **MCP Gateway** is the managed entry point that connects AI agents to your product's APIs through the Model Context Protocol (MCP).

- Hosted and orchestrated by Agen for SaaS at a unique URL (e.g., `your-id.mcp-gw.frontegg.com`).
- Exposes your APIs as **Tools** that AI agents can discover and invoke.
- Enforces authentication, access control, policies, data protection, and hooks on every request.
- Provides a **Test MCP Server** button to verify your gateway is operational at any time.


The gateway URL is auto-generated when you create your server and can be copied directly from the control plane or the Configuration tab.

### Sources

A **Source** is a connection to an external API or service that provides the tools your AI agents can use. Agen for SaaS supports three source types:

| Source type | Description | Input format |
|  --- | --- | --- |
| **REST** | Connect a REST API by uploading or pasting an OpenAPI (Swagger) specification. Agen for SaaS extracts endpoints and parameters automatically. | OpenAPI 3.0 JSON |
| **GraphQL** | Connect a GraphQL API by uploading or pasting a GraphQL schema. Queries, mutations, and types are extracted automatically. | GraphQL SDL |
| **MCP server** | Connect a remote MCP server by providing its URL. Tools are discovered through the MCP protocol. | MCP URL |


Each source has a name, an API base URL, connected tools, and an enabled/disabled toggle. When you add a REST or GraphQL source, click **Generate tools** to automatically create tools from your API specification.

### Tools

A **Tool** represents a single API operation that an AI agent can invoke through Agen for SaaS.

Each tool has:

- **Tool name** — A unique identifier (e.g., `Create_a_new_expense`, `Get_receipt_by_ID`).
- **Tool description** — A human-readable explanation of what the tool does (up to 2,000 characters). This description is what AI agents use to understand the tool's purpose.
- **Tool API** — The HTTP method (GET, POST, PUT, DELETE) and path (e.g., `/api/receipts/{id}`).
- **Source name** — Which source the tool belongs to (e.g., `default`, `Frontegg`).
- **Enable toggle** — Tools can be individually enabled or disabled without deletion.


Tools are auto-generated when you add a source, but you can edit any tool's name, description, method, and path after creation. You can also delete tools that are no longer needed.

### Authentication

Agen for SaaS authenticates every request that passes through the MCP Gateway. Two authentication providers are supported:

| Provider | Description |
|  --- | --- |
| **Frontegg** | Uses Frontegg as the identity provider. An authorization server federation URL is auto-generated (e.g., `your-id.frontegg.com`). |
| **Open ID** | Connect any OIDC-compliant identity provider (Auth0, Cognito, Firebase, Keycloak, Azure AD) using standard OAuth 2.0 credentials. |


You can optionally configure a **custom domain** for your authentication endpoint through a two-step wizard (add domain, then configure DNS records).

### Access control (RBAC / ABAC)

Access control defines **who can invoke which tools** by mapping tools to JWT attributes.

Each access control rule (called a **mapping**) consists of:

- **Mapping name** — A descriptive label (e.g., "Admin only: Delete_expense").
- **Tools** — One or more tools this rule applies to.
- **Mapping type** — Either **Map to roles** (RBAC) or **Map to permissions** (ABAC). This choice is permanent and cannot be changed after creation.
  - **Map to roles** — Restricts tool access to users with specific roles (e.g., "Read Only", "Admin").
  - **Map to permissions** — Restricts tool access to users with specific permissions (e.g., "Read event categories").


Access control rules are evaluated against the JWT claims in every incoming request. If a user lacks the required role or permission, the tool call is blocked.

### Policies and guardrails

**Policies** define conditional rules that control what happens when an AI agent calls a tool. Each policy evaluates request attributes and triggers an action.

A policy consists of:

- **Name and description** — Identify the policy's purpose.
- **Policy tools** — Which tools the policy applies to.
- **Policy attributes** — Conditional expressions using the format: **IF** `[Attribute]` `[Operator]` `[Value]` (e.g., IF `IP` `Contains` `192.168`). Multiple conditions can be combined with **+ and**.
- **Policy action** — The enforcement action when conditions match:


| Action | Behavior |
|  --- | --- |
| **Deny** | The tool call is blocked. |
| **Step up** | The user must provide additional authentication before proceeding. |
| **Request approval** | The tool call is paused and routed to a configured approval flow for human review. |


Policies can be toggled on/off, filtered by action type, and targeted at specific tools. Each policy shows its type (Global or tool-specific), action, and targeting expression in the list view.

### Approval flows

When a policy triggers a **Request approval** action, an **Approval flow** defines who reviews and approves the request.

Creating an approval flow is a four-step process:

1. **General settings** — Set the flow name, description, and activation status.
2. **Channel configuration** — Enable notification channels:
  - **Email** — Send approval requests to approvers' email addresses.
  - **SMS** — Send short approval requests as text messages.
3. **Approval management** — Define the approval sequence using a visual flow builder:
  - Add approval steps with approvers defined by **role** or **email address**.
  - Set the **required minimum number of approvers** for each step.
  - Steps are executed sequentially (Start flow → Step 1 → Step 2 → ... → End flow).
4. **Advanced settings** — Fine-tune behavior:
  - **Auto-approve timeout** — Automatically approve requests that remain pending beyond a specified time.
  - **Send reminder** — Nudge approvers if a request stays pending.
  - **Notify requester on decision** — Inform the requester when their request is approved or rejected.
  - **CC traditional recipients** — Send copies of all approval decisions to additional stakeholders.


### Data protection

**Data protection** policies mask sensitive information in tool responses to maintain compliance with regulations like GDPR, HIPAA, and CCPA.

Each data protection policy defines:

- **Policy name and description** — Identify the policy's purpose.
- **Data types to protect** — Select from categorized sensitive data types:
  - **PHI** — Protected Health Information (39 types including Medicare numbers, health IDs, insurance numbers).
  - **PII** — Personally Identifiable Information.
  - **GDPR** — EU data protection categories.
  - Additional compliance categories (PCI, CCPA, COPPA).
- **Policy tools** — Which tools this masking applies to.
- **Policy targeting** — Conditional expressions that determine when masking is applied (e.g., IF `Country` `In` `United States`).


Data protection policies have a status toggle and can be activated or deactivated at any time.

### Hooks

**Hooks** allow you to execute custom JavaScript code when specific MCP events occur. There are two hook types:

| Hook type | Trigger |
|  --- | --- |
| **Call tool** | Executes when an AI agent invokes a tool. |
| **List tools** | Executes when an AI agent requests the list of available tools. |


Each hook includes:

- **Body** — A JavaScript code editor with a default template. The `onEvent(eventData)` function receives the event details and returns a `verdict` (`'allow'` or `'deny'`) along with an optional `response` object.
- **Settings** — Configure the **fail methodology** (e.g., "Fail Open" to allow requests when the hook fails) and **timeout** (default: 5 seconds).
- **Test** button — Validate your hook logic before activation.
- **Activate/Inactivate** toggle — Control whether the hook is active.


Hooks enable advanced use cases like custom validation, request transformation, dynamic tool filtering, and external service integration.

### Configuration

The **Configuration** tab manages your MCP server's basic settings:

- **Basic configuration**:
  - **Server name** — The display name for your MCP server (e.g., "Expense Management App").
  - **MCP Gateway URL** — The auto-generated endpoint (e.g., `your-id.mcp-gw.frontegg.com`). Read-only, with a copy button.
  - **Custom domain** — Optionally map a custom domain to your MCP Gateway through a two-step DNS configuration wizard.
- **Allowed origins**:
  - Controls which origins can access your Agen for SaaS app, enforced by the `Origin` header.
  - Pre-populated with `{{APP_URL}}` and `{{LOGIN_URL}}`.
  - Add additional origins as needed. Changes take up to 5 minutes to take effect.


### Monitoring and auditing

All actions within Agen for SaaS are logged for transparency and compliance. The monitoring system records:

- Which user or AI agent invoked which tool.
- When the request occurred.
- Which policies, access control rules, or approvals were triggered.
- The full request and response payloads.


Logs can be viewed in the dashboard, streamed to third-party platforms (Datadog, Splunk, AWS EventBridge), and filtered by time, tool, user, or action.

### How the layers interact

| Layer | Role |
|  --- | --- |
| **AI agent** | The customer's AI platform (ChatGPT, Claude, Gemini) initiates a tool call. |
| **MCP Gateway** | Receives the request and routes it through the governance pipeline. |
| → Authentication | Validates the request's identity token. |
| → Access control | Checks whether the user's roles/permissions allow the tool call. |
| → Policies | Evaluates conditional rules and applies deny, step-up, or approval actions. |
| → Approval flows | Routes requests to human reviewers when required by a policy. |
| → Data protection | Masks sensitive fields in the response before returning to the agent. |
| → Hooks | Executes custom JavaScript logic at call-time or list-time. |
| → Monitoring | Logs the entire interaction for audit and compliance. |
| **Your SaaS APIs (Tools)** | The underlying REST, GraphQL, or MCP endpoints that perform the business action. |


### Related topics

- [Overview](/agen-for-saas/introduction/overview)
- [Quickstart](/agen-for-saas/getting-started/quickstart)
- [Sources](/agen-for-saas/sources/overview)
- [Tools](/agen-for-saas/tools/about-tools)
- [Policies](/agen-for-saas/policies/overview)
- [Hooks](/agen-for-saas/hooks/overview)
- [Data protection](/agen-for-saas/data-protection/overview)